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Introduction 



This manual, as its name implies, is meant to be a source of reference information 
about Tektronix Smalltalk. Use this manual when you seek information about a 
class, such as its protocol, background to relate the class to other Smalltalk classes 
and the world outside Smalltalk, and examples of how to use the class. If you are 
new to Smalltalk or need a topical approach to a problem, you should read the 
Tetronix Smalltalk Users manual before, or in addition to, looking here. Since this 
manual does not cover all Smalltalk classes, you might want to refer to other 
Smalltalk texts. 

The first edition of the Tektromx Smalltalk Reference manual contains Smalltalk 
classes added to the system by Tektronix and classes which appeared in Smalltalk- 
80 but have been substantially revised or enlarged by Tektronix. This edition 
includes 47 classes that fit those criteria for inclusion. Future editions of the manual 
will document classes meeting the same criteria as this edition, plus classes which 
have not been previously documented in print. Other information which has been 
proposed for inclusion in future editions includes 

• Pool Dictionaries, 

• Global Variables, 

• Error Messages, and 

• File Formats. 

Arrangement of this Book 

Following this introduction you will find the classes arranged alphabetically. The 
alphabetic arrangement of classes will continue in future editions, and additional 
sections for the information outlined above will follow the classes. 

There are some classes in Tektronix Smalltalk images which are operating system 
specific. They only appear in an image released for a particular operating system. 
For example, UnifiexSystemCall does not appear in the TB2.2.1 image released 
with the UTek operating system. The system dependency (e.g., (UniFLEX only)) is 
noted in the upper right corner of the class' documentation in the manual. Classes 
in this release which are UTek-dependent are not indicated in that manner, because 
all users of this manual have the image for the UTek operating system. 
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Contents of Class Entries 

The figure below is an example of the standard format which begins each class 
entry. 



© 



© 



AbstractSystemCall 



i. 



OS-interface 



® 



Object subclass: #AbstractSystemCall 

instanceVariableNames: 'operationType operation ' 

classVariableNames: 'ErrorMessages ' 

poolDictionaries: 'ErrorConstants OSConstants 

category: 'OS-Interface' 



©- 



''Summary 



This is an abstract class which represents operational requests to some underlying 
operating system. Several assumptions are . . . 
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Partial Class Entry (Sample) 

Explanation 

QJ — class name 
© — class category 
(^ — class definition 
@ — class comment 

Parts 1 through 4 of every entry contain information extracted directly from the 
image, if a class is operating system-dependent (or otherwise release-specific), that 
restriction is included in Part 2. 

Additional Parts of Class Entries 

After the Summary, class entries vary. The following is a complete list of sections 
which appear in various classes, in the order of their appearance. 
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Instance Variables 

An alphabetic list of instance variables, their default class, and a brief 
description of each variable. 

Inherited Instance Variables 

Sometimes this is included to explain class-specific usage of inherited 
variables. It follows the format of the Instance Variables. 

Class Variables 

An alphabetic list of class variables, their default class, and a brief description of 
each variable. An exception to the usual format was made for concrete classes 
in the ExternalData hierarchy. The conventions established for defining their 
class variables are discussed under the appropriate superclass, 
ExternalBinaryData or ExternalPointerData. 

Inherited Class Variables 

Sometimes this is included to explain class-specific usage of inherited 
variables. It follows the format of the Class Variables. 

Pool Dictionaries 

An alphabetic list of shared pools and a brief description of each dictionary. 

Inherited Pool Dictionaries 

Sometimes this is included to explain class-specific usage of inherited shared 
pools. It follows the format of the Pool Dictionaries. 



Instance Methods 



message category 

messageSelector 

method comment 



NameOfClass class 

instanceVariableNames: 'namel name2 etc' 



The box above only appears if a class has class instance variables. 

NameOfClass class — Instance Variables 

An alphabetic list of class instance variables, their default class, and a brief 
description of each variable. 
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Class Methods 



message category 

messageSelector 

method comment 

Rationale 

The purpose of this class — why it's in the image. 

Background 

Information relating this class to other classes and, sometimes, to the operating 
system. 

Discussion 

Implementation information, a description of the class' protocol, practical 
advice. 

Examples 

"How to" information, sample code using the class and an explanation of the 
sample code. When the example is taken from the image, its class location is 
given. 

Related Classes 

Classes are listed if they would be helpful in the understanding of this class. 
The list might include subclasses (if any), other classes often used with this 
class, and the superclass. Classes are listed here even if they are not currently 
included in this manual. 

Typeface and Font Conventions 

Some conventions were established for the use of fonts and typefaces in the 
Summary, Rationale, Background, Discussion, Examples, and Related Classes 
sections of each entry. Different fonts and typefaces were usually not used in 
method comments, nor in the descriptions of instance variables, class variables, 
pool dictionaries, and class instance variables. Those parts are derived from the 
released image. Occasionally, an engineer has used the '#' symbol to denote a 
global variable in method or variable comments (e.g global variable #0S . . .). 

• Code fragments and example code appear in a serif font, for example: 

Transcript show: . . . 

• Information that you would type at the keyboard appears in a monospaced 
(typewriter-style) font, for example: 

. . . bring up the standard image by typing Smalltalk, you . . . 
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• A bold face is used for the names of classes, instance and class variables, pool 
dictionaries, global variables, and message selectors. 

global variables: 

. . , install the appropriate subclass as OS . . . 
. . . path relative to Disk . . . 

class name and message selector: 

. . . using the PositionableStream method nextCNumber . . . 

Instance variables and shared variables: 

... the value at DefaultTextStyle in the TextConstants dictionary . . . 

(TextConstants is a shared pool.) 
. . . deal with the Forms in the glyphs instance variable . . . 
... the class variable BrkcDatalndex holds the offset . . . 
. . . the sizelnBytes class instance variable . . . 

• italic is used for the names of UTek system calls and utilities, for file and path 
names, the names of protocols (also called "message categories"), and 
temporary variables in example code. 

UTek system calls and utilities: 

. . . access the UTek program wc. 
... some filters such as cat, which . . . 
... the accept(2) system call . . . 

book titles and sections of UTek Command Reference: 

. . . documented under inet(4) in the manual UTek Command Reference, 
Volume 2. 

temporary variables: 

... the three temporary variables in, out, and err 
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file names and path names: 

. . . Examples are BertrandVariablel2. font . . . 
. . . structure is found in syslun.h. 

protocols (message categories): 

. . . tlie initialize-release metliod initlallzeFrom:. 

About Preliminary Manuals 

Tlie first time a manual is publishied it may contain some inaccuracies or be 
incomplete — this manual is considered a preliminary manual. Your comments 
and corrections are encouraged, so that the next edition of this manual will be an 
improvement and no longer be preliminary. In the case of this particular manual, the 
term "preliminary" is appropriate because important information that is expected in a 
reference manual has not been included. As explained above, new sections 
providing information in addition to the classes will appear in future editions. 

What Do You Think? 

Eventually, it would be great if this manual documented every class in Tektronix 
Smalltalk. That's a long-range plan. Until that time, you might want to make known 
your nominations for the classes or class categories that you want documented. 
Aside from that, write about your gripes (or even what you like!) and someone 
responsible for this documentation will respond — that's a promise. 

Send your correspondence about this manual to: 

Tektronix, Inc. 

P.O. Box 500, M.S. 50-470 

Beaverton, OR 97077 

Attn: Tektronix Smalltalk Reference Manual 
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Object subclass: #AbstractFileStatus 

instance VariableNames: 

class VariableNames: 

poolDictionarles: 

category: 'OS- Interface' 



Summary 

AbstractFileStatus is an abstract class which represents the status of an operating 
system file. Instances of concrete subclasses of this class encapsulate information 
about a file status. 

A file status is returned by the portable operations named 
status: 
and 
statusName: 

which are defined by the system call class for your operating system, referred to by 
the global variable OS. 



Instance Methods 

accessing 
buffer 



Answer the buffer which holds the file status information. Subclass 
responsibility. 

description 

Answer a String that contains a short description (file size and last 
modification time) of the receiver. 

fileSize 

Answer the file size in bytes. Subclass responsibility. 

isDirectory 

Answer whether the receiver describes a directory. Subclass responsibility. 
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isReadabId 

Answer true if the file represented by the receiver is readable. Subclass 
responsibility. 

isWrltable 

Answer true if the file represented by the receiver is writable. Subclass 
responsibility. 

lastModified 

Answer the time of the last modification to the file. Subclass responsibility. 

comparing 

= aFileStatus 

Answer true if the receiver and aFileStatus describe the same file. Subclass 
responsibility. 

hash 

Hash is reimplemented because = is implemented. Subclass responsibility. 

copying 

copy 

Answer another instance just like the receiver. 

Rationale 

The operating system maintains many pieces of information about a file, such as 
read and write permissions. File status Information is available directly through the 
file status class for your operating system, or indirectly through FlleStream. 

AbstractFileStatus establishes the pattern of protocol to be. included in concrete 
subclasses for different operating systems. As an abstract class it provides a 
portable view of file status. 

To obtain information about a file, the message selectors defined by this class are 
preferred. Methods are implemented in the appropriate subclass for your operating 
system. The subclass for your operating system may have additional methods to 
provide pieces of file status information unique to your operating system. 

Related Classes 

Subclasses: 

UTekFlleStatus 
UniflexFileStatus 

You might want to review the protocol for accessing file status information provided 
by FlleStream. • 
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Object subclass: #AbstractSystemCall 

instanceVariableNames: 'operationType operation ' 

classVariableNames: 'ErrorMessages ' 

poolDictionaries: 'ErrorConstants OSConstants 

category: 'OS-Interface' 



Summary 

This is an abstract class which represents operational requests to some underlying 
operating system. Several assumptions are made about this operating system: 

It has multiple directories that contain files and/or other directories. 

It has files that have some form of status information and can be randomly read, 
written, and truncated. 

It has some means of running other programs. Multi-tasking is not assumed. 

It has some facility, such as pipes, for communicating with other running 
programs. 

It has file descriptors, which are used for uniquely Identifying files and pipes. 

It has some means of receiving and sending interrupts. 

Instances of concrete subclasses of this class encapsulate all information involved 
in making a single request to the operating system. This typically includes 
arguments, results, and control information. 

System calls are performed by creating an Instance containing the arguments for the 
call and then sending an "execution" message to the instance. Subclasses will 
typically define instance creation messages for all possible system calls supported 
by the host operating system. 

The class protocol also defines a set of "portable" or generic operations. These high 
level functions are expected to be supported by any modern operating system. 
These operations are performed by sending a message directly to the class, which 
will cause the operations to be performed and the result returned. It is the 
responsibility of the subclasses to provide the system dependent implementation of 
these operations. 
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Wherever possible, the "portable" operations should be used to ensure operating 
system independence. The global variable OS is set to a subclass of 
AbstractSystemCall, as appropriate for the system. OS should be used in code 
(instead of the name of your system call class) to insure the portability of the code. 

Instance Variables 

operation <SmalIInteger> 

Operation code passed to the operating system. 

operationType <Symbol> 

identifies which type of operating system interface (which primitive) this call 
uses. 

Class Variables 

ErrorMessages <Array> 

An Array of error messages Strings indexed by the integer returned by the 
message errorCode. 

Pool Dictionaries 

ErrorConstants 

Symbolic names are associated with error codes. 

OSConstants 

Symbolic names are associated with constants used by the various 
operating systems. 



Instance Methods 

constants 



constant: aString 

Return a value from the OSConstants or ErrorConstants pool that 
corresponds to aString. If aString is not found, notify the user that it is a 
bad key. This method need only be used for keys that are illegal Smalltalk 
identifiers (i.e., contain the underscore character), othen/vise, the pool key 
name can be used directly by classes that declare the appropriate pool 
dictionaries. 
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errors 



errorCoda 

Return an integer which identifies an error condition. This may not be valid 
if no error has occurred. Subclass responsibility. 

errorCodeFor: errorString 

Answer a value from the ErrorConstants pool that corresponds to aString. 
If aString is not found, notify the user that it is a bad key. 

errorKeyword 

Return a keyword associated with the present error condition. 

errorKeyvi/ordFor: errorlndex 

Answer a keyword from the ErrorConstants pool that corresponds to 
errorlndex. If none is found, return a String representation of the 
errorlndex. 

errorString 

Return a long, descriptive string describing the present error condition. If 
there is no string available, return aString representation of the error code. 

issueError 

Issue a notifier with a string that is associated with the present error code. 
If there is no string available, issue a notifier with the error code. 



execution 



environmentlnvoke 

Return various system information depending on the value of the operation 
instance variable. Possible values of operation are: 

operation system information 

1 command line arguments' address 

2 environment variables' address 

3 hardware configuration block address (UTek only) 

4 interpreter version string' address 

5 copyright string address 

6 OS and machine identification 

7 Smalllnteger time correction 
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invoke 

Perform the system call, return true if it executed without error, return false 
otherwise. Users of #invoke must check the return value if they expect 
valid results! Subclass responsibility. 

value 

Evaluate the system call represented by the receiver. Create an error 
notifier if the system call results in an error. 

vaiuelfError: aBlock 

Evaluate the system call represented by the receiver. Evaluate aBlock if 
the system call resulted in an error. 

operation type 

environmentOperation 

The desired operation involves an environment request. 



Class Methods 



class initialization 

initialize 

Initialize the pool dictionaries and class variables used by 
AbstractSystemCall and its subclasses. This should be overridden by a 
concrete subclass. 

Install 

This message is normally executed by a concrete subclass of 
AbstractSystemCall, causing that subclass to become known by the global 
variable #0S. 

whoAmI 

This message attempts to determine which concrete subclass is a valid 
value for the global variable #OS. 

constants 

constant: aString 

Return a value from the OSConstants or ErrorConstants pool that 
corresponds to aString. If aString is not found, notify the user that it is a 
bad key. This method need only be used for keys that are illegal Smalltalk 
identifiers (i.e., contain the underscore character), otherwise, the pool key 
name can be used directly. 
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errorKeywordFor: errorlndex 

Return a String from the ErrorConstants pool that corresponds to 
errorlndex. If none is found, return a String representation of the 
errorlndex. 

errorValueFor: errorString 

Return a value from the ErrorConstants pool that corresponds to aString. If 
aString is not found, notify the user that it is a bad key. This method need 
only be used for keys that are illegal Smalltalk identifiers (i.e.. contain the 
underscore character, for example, 'EDFS_CD'), otherwise, the variable 
names can be used directly. 

keysAtValue: val 

Return a SortedCollection of all OSConstants keywords that are associated 
with the value val. 

keywordsForConstant: val 

Return a SortedCollection of all OSConstants keywords that are associated 
with the value val. 



filenames 



backupFJieNama: aFileName 

Answer a string which is a backup file name for the file named, aFileName. 
Subclass responsibility. 

checkFileName: aFileName fixErrors: fixErrors 

Check aFileName for validity as a file name. If there are problems (e.g., 
illegal length or characters) and fixErrors is false, notify an error. If there 
are problems and fixErrors is true, make the name legal (by omitting illegal 
characters) and answer the new name. Otherwise, answer the name. 
Subclass responsibility. 

completePathname: aDirectoryName 

Answer the complete path name of the string, aDirectoryName, starting at 
the root of the file system. A trailing path name separator is considered 
part of a directory name even if not explicitly stored. Subclass responsibility. 
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currentDirectoryPseudonym 

Answer the string which represents the name for the current directory. 
Subclass responsibility. 

fileDirectory: aFileDirectory dIrectoryName: aFiieName 

Answer a file directory name derived from the string, aFiieName, and the 
file directory, aFileDirectory. Subclass responsibility. 

fullDlrectoryName: aDirectoryName 

Answer the full path name of the string, aDirectoryName, starting at the 
directory Disk. A trailing path name separator is considered part of a 
directory name even if not explicitly stored. Subclass responsibility. 

isBackupFiieName: aFiieName 

Does aFiieName correspond to a name that is usually a backup file name? 
Subclass responsibility. 

isFiieDirectoryName: aFiieName 

Is aFiieName the name of a directory? Subclass responsibility. 

islnvisibleFileName: aFiieName 

Is aFiieName such that it would normally not be displayed in a file listing? 
Subclass responsibility. 

separateDirectoryNameAndFileName: aFiieName 

Split the string, aFiieName, into a directory name and a file name within the 
directory. Return an Array of two elements. Array at: 1 is the directory 
name. Array at: 2 is the file name. Subclass responsibility. 

general inquiries 

asTlme: osSeconds 

Convert the operating system's notion of time to a Time. Subclass 
responsibility. 

defaultlnterruptCode 

Answer an operating system representation of the default interrupt action. 
Subclass responsibility. 

fileStatusClass 

Return the class used to store file status returned by system calls that 
return information about files. Subclass responsibility. 
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fontDirectory 

Return the FileDirectory which contains font files. Each file contains a font 
in external font format. Subclass responsibility. 

ignorelnterruptCode 

Answer an operating system representation of the ignore interrupt action. 
Subclass responsibility, 

isValld 

Does this class represent the operating system running on this machine? 
(This method must return true in only one subclass.) 

maxFileNameSize 

Answer the maximum number of characters permissible in file names. 
Subclass responsibility. 

maxOpenFiles 

Answer the maximum number of files that may be open at one time. 
Subclass responsibility. 

smalltalklnitializationDirectory 

Return the FileDirectory which contains initialization files. Each file 
contains Smalltalk readable data used during class initialization. Subclass 
responsibility. 

Smalltalk InterpreterVersionString 

Return a String identifying the Smalltalk interpreter that is currently running. 
Subclass responsibility. 

textLineDelimiter 

Answer a String containing the characters which delimit a 'line' in a file. 
Subclass responsibility. 

portable directory operations 

changeDirectory: directoryName 

Change the current directory to the specified directory. Subclass 
responsibility. 

createDlrectory: directoryName 

Create a new directory with the name directoryName. Subclass 
responsibility. 
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currentDlrectoryName 

Return a String with tlie name of the current working directory. Subclass 
responsibility. 

nextFileName: directoryStream 

Answer the next file name in directoryStream. Advance the directory 
stream beyond that name. Answer nil If none. Avoid recursion; do not 
return the current directory, even if it is next. Subclass responsibility. 

removeDlrectory: directoryName 

Remove the directory named aDirectoryName. Subclass responsibility. 

portable file operations 

closeFiie: aFileDescriptor 

Close the file referred to by aFileDescriptor. Subclass responsibility. 

create: aString 

Create a new file named aString. Answer a writeOnly fileDescriptor for the 
file. Subclass responsibility. 

existlngName: fileName 

Answer true if a file or directory named fileName exists. Subclass 
responsibility. 

freeFileDescrlptors 

Answer the number of available file descriptors. For some operating 
systems this might be a very large number! Subclass responsibility. 

open: fileName 

Open the file named fileName. Answer a readWrite fileDescriptor for the 
file. Subclass responsibility. 

openForRead: fileName 

Open the file named fileName. Answer a readonly fileDescriptor for the 
file. Subclass responsibility. 

openForWrite: fileName 

Open the file named fileName. Answer a writeOnly fileDescriptor for the 
file. Subclass responsibility. 

read: fileDescriptor Into: aStrlngOrByteArray 

Fill aStrlngOrByteArray with data from the file referred to by fileDescriptor. 
Return the number of bytes read, or zero if at end. Subclass responsibility. 



16 



AbstractSystemCall os-interface 



read: fileDescriptor Into: aStringOrByteArray size: count 

Fill aStringOrByteArray with, at most, count data elements from the file 
referred to by fileDescriptor. Return the number of bytes read, or zero if at 
end. Subclass responsibility. 

remove: fileName 

Remove the file named fileName. Subclass responsibility. 

rename: fileName as: newFileName 

Rename the file named fileName to have the name newFileName, Notify 
an error if fileName does not exist; but not if newFileName exists. Subclass 
responsibility. 

seek: aFileDescriptorto: aFilePosltion 

Position the file known by aFileDescriptor to aFilePosition bytes from its 
beginning. Subclass responsibility. 

shorten: fileDescriptor 

Shorten a file to its current position. Subclass responsibility. 

size: fd 

Return the count of available bytes from the file or pipe known by the file 
descriptor fd. Subclass responsibility. 

status: fileDescriptor 

Answer a FileStatus for the file referred to by its fileDescriptor. Subclass 
responsibility. 

statusName: fileName 

Answer a FileStatus for the file named fileName. Subclass responsibility. 

validFileDescriptor: fileDescriptor 

Answer true if an open file with the specified file descriptor exists. Subclass 
responsibility. 

write: fileDescriptor from: aStringOrByteArray size: byteCount 

Write byteCount bytes of data from aStringOrByteArray to the file known by 
fileDescriptor. Subclass responsibility. 



portable subtask operations 

defaultlnterrupt: aninterruptID 

Set the specified interrupt to its default action. 
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executeUtlllty: aCommand wlthArguments: anOrderedCollection 

Execute a binary program and return the entire results generated by the 
program as a string. No mechanism for input to the executable program is 
provided. Notify an error if the program cannot be executed or if the 
program terminates abnormally. Subclass responsibility. 

executeUtllltyWithErrorlVlappIng: aCommand 
withArguments: anOrderedCollection 

Execute a binary program and return an array of two strings. The first 
string contains the entire normal output generated by the program. The 
second string contains any error message output from the program. No 
mechanism for input to the executable program is provided. Notify an error 
if the program cannot be executed or if the program terminates abnormally. 
Subclass responsibility. 

Ignorelnterrupt: anInterruptID 

Set the specified interrupt to be ignored. 

setlnterrupt: interruptID to: aSemaphoreOrParameter 

Override the default action for the interrupt known by interruptID by 
connecting it to a semaphore or some system specific parameter. If 
specified, the semaphore is posted on interrupt. The state of the interrupt 
once it has been received is system dependent. Subclass responsibility. 

shell 

Cause control to be passed to the operating system command interpreter. 
Return to Smalltalk is system dependent. Subclass responsibility. 

Rationale 

There was a desire to move system call dependencies from individual classes like 
FileStreann, Pipe, and Subtask to one hierarchy and implement them there so that 
they are more easily maintained for different operating systems. A hierarchy was 
established to deal with multiple operating systems. AbstractSystemCall was 
created to define a minimum set of services to be provided to Smalltalk by any 
operating system. AbstractSystemCall defines those services with selector names 
that an application program can use and guarantee portability to any Tektronix 
Smalltalk operating system. 

AbstractSystemCall establishes the pattern of protocol to be included in concrete 
subclasses. Some protocol for generic services is implemented in this class 
(instead of being a subclass responsibility), but much of it is reimplemented in 
subclasses. A concrete subclass of this class is assigned as the value of the global 
variable OS. In code, OS is used for portability, instead of the name of a system call 
class, unless the application is meant to be used only with a specific operating 
system. 



18 



AbstractSystemCall os-interface 



The class variables are declared in AbstractSystemCall so that they are named in 
one place, and are initialized by separate system call classes. 

Discussion 

Since it is an abstract class, there is no instance creation protocol for this class. The 
protocol here is a template for subclasses. To mal<e a system call, create an 
instance of a subclass. Read about the system call class for your operating system 
in this manual. It will implement the protocol found here, plus additional protocol 
which is operating system dependent. 

Class Protocol 

Class initialization methods intialize the class variables and pool dictionaries, install 
the appropriate subclass as OS, and determine which subclass should be OS. The 
initialize method returns self, because that method should be overridden by a 
subclass. You might have use for the whoAmI message in operating system 
dependent code. If you want to specify a certain operating system in the code, you 
could include something like 

AbstractSystemCall who Ami name = #ParticularSystemCall ifrrue:[ . . . 

Use of the message name and the symbol are needed so that a correct boolean will 
be returned instead of a notifierthat PartlcuIarSystemCall is not recognized. 

Constants methods access the pool dictionaries, ErrorConstants and 
OSConstants. Two methods, constant: and errorValueFor:, access a pool for an 
argument String which contains an underscore or other illegal identifier character. 
Another use for the constant: message is in a workspace, for example, where the 
pool dictionary is not directly accessible. 

File names methods are implemented by a subclass. 

General inquiries methods are implemented by a subclass. 

Portable directory operations methods are implemented by a subclass. 

Portable file operations methods are implemented by a subclass. 

Portable subtask operations methods are implemented by a subclass, except for 
defaultlnterrupt: and Ignorelnterrupt:, which may be overridden by a subclass. 
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Instance Protocol 

Constants has one method, constant:, which calls the class method of the same 
name. 

Errors has several methods for accessing ErrorConstants and specifies one 
method, errorCode, to be implemented by a subclass. Some of the methods 
implemented here are overridden in a subclass. 

Execution has several methods to execute a system call and one method, 
environmentlnvoke, that executes the system call primitive for environment 
operations. Some of the methods implemented here are overridden in a subclass. 

Operation type has one method to set the operationType instance variable for an 
environment operation. 

Examples 

The following code can be executed in a workspace. It will cause the name of your 
system call class to display in the System Transcript. There are no other messages 
that you are likely to send to this class. 

Transcript cr; show: AbstractSystemCall whoAmI printString. 

Related Classes 

Subclass: 

AimSystemCall 
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AbstractSystemCall subclass: #AimSystemCall 


instance VariableNames: 


'DOIn DOOut D1ln D10ut D2ln AOIn AOOut errno 


class VariableNames: 

poolDictionaries: 

category: 


'StrlngTerminator ' 
'OS-Interface' 



Summary 

This is an abstract class which defines the basic mechanism used to perform 
operating system calls on the various Tektronix 4000 series bitmapped workstations. 
It also provides interfaces for accessing the display subsystem, operating system 
environment variables, and the command line arguments used when Smalltalk was 
invoked. 

These system call objects contain all of the information normally used to perform a 
system call by an assembly language programmer. This includes the values of 
machine registers passed to or returned from the system call, any parameters lists, 
the operation ID of the function to be performed, and any error information. Since 
there may be several different interfaces to the underlying operating system, 
instances also contain a field which identifies which particular type of interface 
needs to be used. Input and output parameter descriptors are defined in 
subclasses. 

Instance Variables 

AOIn <Object> 

An input parameter descriptor for the value to be passed in AO. 

AOOut <Object> 

An output parameter descriptor for the value to be returned in AO. 

DOIn <Object> 

An input parameter descriptor for the value to be passed in DO. 

DOOut <Object> 

An output parameter descriptor for the value to be returned in DO. 

D1ln <Object> 

An input parameter descriptor for the value to be passed in D1 . 
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D1 Out <Object> 

An output parameter descriptor for the value to be returned in D1 . 

D2In <Object> 

An input parameter descriptor for the value to be passed in D2. 

errno <Smalllnteger or nil> 

Error code return by the operating system, nil if no error. 

Class Variables 

StrlngTerminator <String> 

This must be appended to strings before sending them to the operating 
system. 



Instance Methods 

initialize-release 



DOIn: din DOOut: dout AOIn: ain AOOut: aout 

Set D and A registers. Set unspecified input registers to nil and 
unspecified output registers to false. 

DOIn:dOin DOOut: dOoutDlln: d1 in D10ut:d1out D2In:d2in 
Set D registers. 

D1ln:d1in D10ut:d1out 
Set D1 registers. 

operation: opcode with: argO 
operation: opcode with: argO with: arg1 
operation: opcode with: argO with: arg1 with: arg2 
operation: opcode with: argO with: arg1 with: arg2 with: arg3 
operation: opcode with: argO with: arg1 with: arg2 with: arg3 with: arg4 
operation: opcode with: argO with: arg1 with: arg2 with: arg3 with: arg4 

with: argS 

Set up the arguments for a system call. Set the operation to the proper 

code. 



accessing 
AOOut 



Return the value of the instance variable AOOut. 

DOOut 

Return the value of the instance variable DOOut. 
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D10ut 

Return the value of the instance variable DIOut. 



errors 



errorCode 

Return an integer which identifies an error condition. This may not be valid 
if no error has occurred. 

execution 

displaylnvoke 

Perform a display system call. 

invoke 

Perform the system call, return true if it executed without error, return false 
otherwise. Users of #invoke must check the return value if they expect 
valid results! 

systemlnvoke 

Make a system call. Return success or failure of that system call. Notify if 
the primitive failed. 

operation type 

displayOperation 

The desired operation involves the display. 

operation 

Return the current operation. 

operation: opcode 

Set the code of the operation. 

systemOperation 

The desired operation involves the operating system. 

portable subtask operations 

terminatedSubtaskExitCode 

Return a portion of the status returned from the wait system call. This 
portion represents the value of the argument supplied by the exit system 
call causing termination. The high order bit of the portion indicates whether 
the terminated task has made a core dump. The receiver must be an 
instance representing a wait system call that has been executed. Subclass 
responsibility. 
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terminatedSubtaskExitlnterrupt 

Return a portion of the status returned from the wait system call. This 
portion represents the value of the signal causing termination. The 
receiver must be an instance representing a wait system call that has been 
executed. Subclass responsibility. 

termlnatedSubtaskID 

Return the ID returned from the wait system call. The receiver must be an 
instance representing a wait system call that has been executed. 



Class Methods 



class initialization 

initialize 

Initialize the class variables used by AimSystemCall subclasses. 

environment variables 

argCount 

Return the number of arguments on the command line used to invoke 
Smalltalk. Subclass responsibility. 

origlnalEnvironment 

Return the operating system environment variables in use when Smalltalk 
was invoked. Subclass responsibility. 

filenames 

checkFlIeName: aFileName fixErrors: fixErrors 

Check aFileName for validity as a file name. If there are problems (e.g., 
illegal length or characters) and fixErrors is false, notify an error. If there 
are problems and fixErrors is true, make the name legal (by omitting illegal 
characters) and answer the new name. Otherwise, answer the name. 
Control characters, spaces, rubouts, and all characters with an ASCII value 
greater than 127 will be considered illegal. 

completePathname: aDirectoryName 

Answer the complete path name of the string, aDirectoryName. A trailing 
path name separator is considered part of a directory name even if not 
explicitly stored. 

currentDirectoryPseudonym 

Answer the string which represents the name for the current directory. 
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fileDirectory: aFileDirectory dIrectoryName: aFileName 

Answer a file directory name derived from the string, aFileName, and the 
file directory, aFileDirectory. 

fullDirectoryName: aDirectoryName 

Answer the full path name of the string, aDirectoryName, starting at the 
directory Disk. A trailing path name separator is considered part of a 
directory name even if not explicitly stored. 

IsFileDirectoryName: aFileName 

Is aFileName the name of a directory? 

islnvisibleFileName: aFileName 

Return true if the string, aFileName, is the name of a file which is normally 
not displayed in a directory listing. 

pathNameLevelSeparator 

Answer the character which delimits directory names in a file name path. 

pathNameLevelSeparatorString 

Answer a string containing the character which delimits directory names in 
a file name path. 

separateDirectoryNameAndFileName: aFileName 

Split the string, aFileName, into a directory name and a file name within the 
directory. Return an Array of two elements. Array at: 1 is the directory 
name. Array at: 2 is the file name. 

general inquiries 

abnormalTerminationCode 

Return the code for abnormal task termination. Subclass responsibility. 

brokenPipelnterrupt 

Return the interrupt number for the broken pipes interrupt. Subclass 
responsibility. 

deadChildinterrupt 

Return the interrupt number for the terminated child process interrupt. 
Subclass responsibility. 

getMachineName 

Return the type of machine Smalltalk is running on. Subclass responsibility. 
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nonBIockingWait 

Does this class' #wait method return immediately rather than blocking? 
Subclass responsibility. 

pack: upperlnteger intoRegisterWith: lowerlnteger 

Answer a 32 bit value created by packing the upper and lower Integers 
together. 

prioritylnterval 

Return the interval of valid priorities in order of descending priority for this 
task and effective user. Subclass responsibility. 

returnKeyCode 

Answer Smalltalk character value which should be assigned when the 
return key is pressed. Subclass responsibility. 

smalltalklnterpreterVerslonStrIng 

Return a String identifying the Smalltalk interpreter that is currently running. 

strlngTermlnator 

Return the Character that must be appended to strings before sending 
them off to the operating system. 

termlnatelnterrupt 

Return the interrupt number for the terminate interrupt. This interrupt can 
be caught. Subclass responsibility. 

terminateUnconditionallylnterrupt 

Return the interrupt number for an unconditional termination interrupt. This 
interrupt cannot be caught. Subclass responsibility. 

textLIneDelimiter 

Return a String containing the characters that delimit a 'line' in a file. 

validPrlorlty: aPriority 

Is aPriority a valid priority for this task and user? Subclass responsibility. 

portable file operations 

closeFile: aFileDescriptor 

Close the file referred to by aFileDescriptor. 

dupllcateFd: fileDescriptor 

Return a new file descriptor that references the same open file as 
fileDescriptor. Subclass responsibility. 
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dupIlcateFd: oldFileDescriptor with: newFileDescriptor 

Cause newFileDescriptor to reference tlie same open file as 
oldFileDescriptor. If newFileDescriptor currently references an open file, 
that file is first closed. Subclass responsibility. 

newPIpe 

Return an instance of Pipe. Subclass responsibility. 

remove: fileName 

Remove the file named fileName. 

portable subtask operations 

brokenPipesProcessWIth: aBlock 

Return a process that monitors broken pipes. ABlock is executed after the 
receipt of each broken pipe signal. Subclass responsibility. 

execute: program withArguments: args withEnvIronment: environment 
Answer an instance of the exec system call. It has not been invoked yet. 
Subclass responsibility. 

executeUtillty: aCommand withArguments: anOrderedColIection 

Execute a binary program and return the entire results generated by the 
program as a string. No mechanism for input to the program is provided. 
Notify an error if the program cannot be executed or if the program 
terminates abnormally. 

executeUtilityNoCheck: aCommand withArguments: anOrderedColIection 
Execute a binary program and return the entire results generated by the 
program as a string. No mechanism for input to the program is provided. 
Some utilities (rsh, grep) return abnormal termination status after executing 
successfully — use this method for such programs. 

executeUtliityWithErrorMapping: aCommand 
withArguments: anOrderedColIection 

Execute a binary program and return an array of two strings. The first 
string contains the entire normal output generated by the program. The 
second string contains any error message output from the program. No 
mechanism for input to the executable program is provided. Notify an error 
if the program cannot be executed or if the program terminates abnormally. 

exit: exitParam 

Answer an instance of the exit system call. It has not been invoked yet. 
Subclass responsibility. 
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fork 

Answer an instance of the fork system call. It has not been invoked yet. 
Subclass responsibility. 

forkShell 

Fork an operating system shell. Exit the shell to return to Smalltalk. 
Subclass responsibility. 

sendlnterrupt: interruptID to: tasklD 

Send the interrupt known by interruptID to the task known by tasklD. 
Return true if the operation was successful, false otherwise. Subclass 
responsibility. 

setTaskPrlorlty: priority 

Set the priority of Smalltalk to the value priority. Subclass responsibility. 

startSubtask: executeCall withBlock: childBlock 

Fork a copy of Smalltalk. In the child copy, execute childBlock and invoke 
executeCall, which must be an instantiated 'exec' system call. Subclass 
responsibility. 

terminate: tasklD 

Using an interrupt, attempt to terminate the task known by tasklD, This 
termination is requested in a manner which can be intercepted. Subclass 
responsibility. 

terminatedSubtasksProcessWlth:aBlock 

Return a Process that monitors spawned child tasks. ABIock is executed 
after the termination of each child task. The dead child signal Is 
automatically reset by the operating system. Subclass responsibility. 

terminateUnconditionally: tasklD 

Terminate this task unconditionally. Subclass responsibility. 

wait 

Answer an instance of the wait system call. It has not been invoked yet. 
Subclass responsibility. 



system-display operations 

blackOnWhite 
Normal video. 

cursorOff 

Turn off the cursor. 
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cursorOn 

Turn on the cursor. 

disableCursorPannIng 

Disables panning when the cursor reaches any viewport boundary. 

disableJoydiskPanning 

Disables panning with the joydisk, 

enableCursorPanning 

Enables panning when the cursor reaches any viewport boundary. 

enableJoydiskPanning 

Enables panning with the joydisk. 

getDisplayState: buff 

Return the 36 word status report of the display system. 

getMouseBounds 

Get the limits of mouse movement as a rectangle — upper left in DO, lower 
right in D1. 

getVlewport 

Return the upper left position of the viewport within the display bitmap. 

setMouseBounds: upperXY lowerRlght: lowerXY 

Set the limits of mouse movement to a rectangle — upper left in D1 , lower 
right in D2. 

setViewport: xyCoord 

Set the upper left position of the viewport in the display bitmap. 

timeOutOff 

Disables automatic screen saver. 

timeOutOn 

Enables automatic screen saver. 

turnDisplayOff 

Sets the display to be blanked. 

turnDisplayOn 

Sets the display to be visible. 

whiteOnBlack 
Inverse video. 
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system-environment 

configurationAddress 

Get the address of the configuration block of the machine running this 
Smalltalk. 

copyrightAddress 

Get the address of the copyright string for this Smalltalk interpreter. 

interpreterVersionAddress 

Get the address of the string identifying the version of this Smalltalk 
interpreter. 

invocationArgumentsAddress 

Get the address of the argument array for this invocation of Smalltalk. 

invocationEnvironmentAddress 

Get the address of the environment array for this invocation of Smalltalk. 

machinelDAddress 

Get the address of a string that identifies the operating system and 
machine upon which Smalltalk is running. 

timeCorrectionDifference 

Get a Smalllnteger representing the number of seconds difference between 
UTek time {GUI) and local time. 

system-event operations 

clearAlarm 

Clear the alarm used by the graphics. 

eventsDIsable 
Turn off events. 

eventsEnable 

Turn on events. A side effect of this call is to set keyboard code to zero. 

eventSignalOn 

Produce event signals. 

getAlarmTime 

Get the millisecond timer. 
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setAlarmTime: time 

Set the millisecond timer to the desired time. 

setKeyboardCode: aCode 

Set the keyboard cx)de — sets keyboard to output event codes and 1 
sets the keyboard to output ANSI terminal code. Event codes are what 
Smalltalk expects. 

terminalOff 

Turn off the terminal emulator. 

terminalOn 

Turn on the terminal emulator. 

Rationale 

AimSystemCall is an abstract class that implements protocol related to the display 
subsystem of Tektronix 4000 series bitmapped workstations. These display 
operations are implemented at this level to be inherited by concrete subclasses for 
various operating systems. Other system call protocol that concrete subclasses 
have in common has been implemented at this level. Instance variables are defined 
for data passed in registers when making a system call. A class variable is defined 
for the string terminator that subclass operating systems have in common. 

Discussion 

The protocol here is a template for subclasses. There is no occasion upon which 
you should send a message to this class. To make a system call, create an 
instance of a subclass. Read about the system call class for your operating system 
in this manual. It will implement the protocol found here, plus additional protocol 
which is operating system dependent. 

Class Protocol 

Class initialization contains one method which sets the value of the class variable. It 
calls the abstract superclass method of the same name, which returns self. The 
major work of initializing is done in a subclass method. 

Environment variables methods are implemented by a subclass. 

File names methods answer information about file and directory names, including the 
complete path from root, the path relative to Disk, the character which separates 
levels of the path, the backup file suffix, and concatenates or separates file and 
directory names. These methods are generally used for parsing. 
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General inquiries methods are implemented by a subclass, except for 
strlngTermlnator, which returns the character the operating systems expect at the 
end of strings, pack:intoRegisterWith:, which packs two integers into a 32 bit word, 
and smalltalklnterpretGrVerslonStrIng, which returns the version number of the 
interpreter in a String. 

Portable file operations methods are implemented by a subclass, except for 
closeFile:, which closes a file, and remove:, which removes a file from its directory. 
Those two operations are implemented here because subclasses use the same 
selector to achieve the result of each portable message. 

Portable subtask operations are operations that Smalltalk requires from the operating 
system in order to run a Subtask, a spawned child process from the operating 
system's point of view. AimSystemCall implements the "executeUtility" methods 
which start a subtask. The other methods in this message category are 
implemented by a subclass. 

System-display operations are methods which enable or disable display attributes. 
They are implemented here because they are applicable for all immediate 
subclasses. 

System-environment methods return the address of environment variables at the time 
Smalltalk was invoked, the address of command line arguments, and information 
about the software, including the copyright address, the address of the interpreter 
version, and the adjustment amount between UTek and Smalltalk time. An address 
returned by one of these methods can be converted to a String by sending the 
address as the argument to the String instance creation message fromCStrIng:. 

System-event operations are methods which enable or disable event attributes. Events 
are user-interface occurrences, such as a key-press, mouse movement, and joydisk 
movement. The built-in alarm (timer) and terminal emulator are also included in the 
category of events. Events are implemented here because they are applicable for 
all immediate subclasses. 

Instance Protocoi 

Initialize-release has three methods which set the values of the register instance 
variables plus several methods, overridden by subclasses, which set up the 
operation and arguments to a system call. 

Accessing methods return the values of the "out" instance variables. 
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Errors has one method that returns the value of errno. 

Execution has two methods, displaylnvoke and invoke, which call the proper 
primitive to communicate with the operating system, and systemlnvoke which calls 
a subclass method to make a primitive call. 

Operation type has methods to set the operatlonType instance variable and a 
method that sets and one that returns the value of operation. 

Portable subtask operations are operations which an instance of a subclass would 
perform for a Subtask, such as answer the exit code, the interrupt ID, or the task ID 
of the Subtask. The methods are implemented by a subclass, except 
termlnatedSubtaskID, which returns the value of DOOut. 

Related Classes 

Subclasses: 

UnlflexSystemCall (UniFLEX only) 
UTekSystemCall (UTek only) 

You might also want to look at the superclass, AbstractSystemCall. 
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ExternalBinaryData variableByteSubclass: #DisplayState 



instance VariableNames: 
classVariableNames: 



pooIDictionaries: 
category: 



'BlackOnWhiteBitPositionCursorDatalndex 
CursorLinkedBitPosition CursorOffsetXDatalndex 
CursorOffsetXYDatalndex 
CursorOffsetYDatalndex CursorOnBitPosition 
CursorPanningBitPosition DispIayOnBitPosition 
EventsBitPosition HeightDatalndex 
JoyPanningBitPosition KeyboardCodeDatalndex 
KeyCapsLockLEDBitPosition 
LinelncrementDatalndex 
MouseBoundLrDatalndex 
MouseBoundUIDatalndex 
ScreenSaverBitPosition StateBitsDatalndex 
TerminalEmulatorBitPosition TotalSizeDatalndex 
ViewportDatalndex ViewPortHeightDatalndex 
ViewPortWidthDatalndex WidthDatalndex ' 

'OS-Parameters' 



Summary 

DisplayState captures all of the Information about the state of the display in a single 
class. This class is represented in the operating system as the C structure below. 
DisplayState provides creation and accessing protocol for the structure. 

struct displaystate { 



int 


disp_stateBits; 


/♦ bit definitions as below */ 


int 


disp_viewport; 


/♦ upper left corner point of viewport ♦/ 


int 


disp_mouseBound_ul; 


/* upper left corner point of mouse 
bounds ♦/ 


int 


disp_mouseBoundJr; 


/* lower right corner point of mouse 
bounds */ 


short 


disp_cursor[16]; 


/* the cursor image */ 


char 


disp_keyboardCode; 


/* current keyboard encoding: 
0=events, l^ansi*/ 


char 


disp_reserved1 ; 


/* reserved for future use */ 


short 


dispjine Increment; 


/* number of bytes between scan lines ♦/ 


short 


disp_width; 


/* width of virtual display bitmap */ 



Tektronix Smalltalk Reference Manual 



35 



DisplayState OS-Parameters 



short disp_height; 

short disp_viewPortWidth; 

short disp_viewPortHeight; 

short disp_cursorOffsetX; 

short disp_cursorOffsetY; 

int disp_reserved[2]; 



/* height of virtual display bitmap */ 

/+ width of viewport ♦/ 

/* height of viewport ♦/ 

/* X graphic cursor offset */ 

/* Y graphic cursor offset ♦/ 

/* reserved for future use */ 



name 



stateBits Definition 

bit position * comment 



displayOn 


1 


screenSaver 


2 


blackOnWhite 


3 


terminalEmulator 


4 


l<eyCapsLockLED 


5 


cursorOn 


9 


cursorLinked 


10 


cursorPanning 


11 


joyPanning 


12 


events 


17 



1 means on / means off 

1 means screen saver on / means off 

1 means black on white / means white on black 

1 means emulator output enabled / disabled 

1 means the Caps Lock LED is illuminated 

1 means graphics cursor is enabled 

1 means mouse is linked to cursor 

1 means cursor movement can cause panning 

1 means joydisk causes viewport panning 

1 means events mechanism is turned on 



♦ Smalltalk bit positions are counted from position 1, not as in the C structure 
statebits field. 

The structure is documented under getDisplayState in the system call section of the 
manual that documents platform-specific extensions for your operating system. 

Class Variables 

BlackOnWhiteBitPosItlon 

CursorDatalndex 

CursorLlnkedBltPosition 

CursorOffsetXDatalndGX 

CursorOffsetXYDatalndex 

CursorOffsetYDatalndex 

CursorOnBltPosition 

CursorPannlngBitPosltion 

DisplayOnBitPosition 
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EventsBitPosition 

HeightDatalndex 

JoyPanningBitPosition 

KeyboardCodeDatalndex 

KeyCapsLockLEDBitPosition 

LinelncrementDatalndex 

MouseBoundLrDatalndex 

MouseBoundUIDatalndex 

ScreenSaverBitPosition 

StateBitsDatalndex 

TerminalEmulatorBitPosItlon 

TotalSizeDatalndex 

ViewportDatalndex 

VIewPortHelghtDatalndex 

ViGwPortWidthDatalndex 

WidthDatalndex 

Each C structure class variable holds the offset of a single field in the 
structure. The name of a class variable is constructed from a field name, 
stripped of its prefix, with the string 'Datalndex' appended. For example, 
the class variable StateBitsDatalndex holds the offset of the 
"disp_stateBits'' field. For this structure, each bit position in the 
"disp_stateBits" field has its own class variable. 



Instance Methods 

accessing 



cursorOffsetX 

Return the value of the structure field named cursorOffsetX. 

cursorOffsetY 

Return the value of the structure field named cursorOffsetY. 

height 

Return the value of the structure field named height. 
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keyboardCode 

Return the value of the structure field named keyboardCode. 

Ilnelncrennent 

Return the value of the structure field named linelncrement. 

mouseBoundLr 

Return the value of the structure field named mouseBoundLr. 

mouseBoundLrX 

Return the X coordinate of the value of the structure field named 
mouseBoundLr. 

mouseBoundLrY 

Return the Y coordinate of the value of the structure field named 
mouseBoundLr. 

mouseBoundUl 

Return the value of the structure field named mouseBoundUl. 

mouseBoundUIX 

Return the X coordinate of the value of the structure field named 
mouseBoundUl. 

mouseBoundUlY 

Return the Y coordinate of the value of the structure field named 
mouseBoundUl. 

state Bits 

Return the value of the structure field named stateBits. 

viewport 

Return the value of the structure field named viewport. 

viewPortHeight 

Return the value of the structure field named viewPortHeight. 

viewPortWidth 

Return the value of the structure field named viewPortWidth. 

viewportX 

Return the X coordinate value of the structure field named viewport. 

viewportY 

Return the Y coordinate value of the structure field named viewport. 

width 

Return the value of the structure field named width. 
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accessing-status 

blackOnWhite 

Answer true if the blackOnWhite state bit is set. 

cursorLinked 

Answer true if the cursorLinked state bit is set. 

cursorOn 

Answer true if the cursorOn state bit is set. 

cursorPannIng 

Answer true if the cursorPanning state bit is set. 

displayOn 

Answer true if the displayOn state bit is set. 

events 

Answer true if the events state bit is set. 

joyPannIng 

Answer true if the joyPanning state bit is set. 

keyCapsLocRLED 

Answer true if the keyCapsLockLED state bit is set. 

screenSaver 

Answer true if the screenSaver state bit is set. 

terminaiEmuiator 

Answer true if the terminaiEmuiator state bit is set. 



printing 



prIntOn: aStream 

Print the receiver on aStream. 
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Class Methods 



class initialization 

Initialize 

Assign offset values to the class variables and define the size of the 
structure. 

Rationale 

The display state structure stores in one place all important attributes that affect the 
current environment of the display. The structure is used in support of the following 
system call: 

getDisplayState 

Discussion 

DispIayState does not provide protocol to modify the C structure in the operating 
system. Its purpose is to provide access to the information in the structure. 

AimSystemCall provides protocol for changing the state of the display. Under 
system-display operations you will find methods to enable and disable display 
attributes, for example, inverse/normal video, cursor panning, and joydisk panning. 

See the manual that documents platform-specific extensions for your operating 
system for more information about display attributes and the fields in the 
displaystate structure. 

Related Classes 

AimSystemCall implements the system call getDisplayState which uses the 
displaystate structure. 
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ExternalData variableByteSubclass: #ExternalBinaryData 

instance VariableNames: 

classVariableNames: 

pooIDictionaries: 

category: 'OS-Parameters' 



Summary 

ExternalBinaryData is an abstract class for non-Smalltalk data structures that do 
not have imbedded pointers. The concrete classes representing non-Smalltalk data 
structures are used to pass information between Smalltalk and the operating 
system, for example, when making system calls. The indexable fields of instances 
of subclasses represent the same bytes as the named fields of the external 
language's data structure. This is explained in the "Discussion" section. 

Subclasses implement creation and accessing methods for specific non-Smalltalk 
data types such as displaystate, a C structure, and wait, a C union. 



Instance Methods 

accessing 
data Area 



Answer the data portion of the receiver. 

replaceFrom: start to: stop with: replacement startlngAt: repStart 

This destructively replaces elements from start to stop in the receiver, 
starting at index repStart in the Collection replacement. Answer the 
receiver. 



conversion 



asStrlngFrom: start to: stop 

Create a string from the receiver's bytes between start and stop, inclusive. 



ExternalBinaryData class 

instanceVariableNames: 'sizeinBytes ' 
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ExternalBlnaryData class — Instance Variables 

sizelnBytes <Integer> 

Number of bytes required to represent the data area of an instance. 



Class Methods 



accessing 

numberOfPolnters 

Return the number of pointers imbedded in the structure represented by an 
instance of the receiver. 

pointersSize 

Answer the pointers size of any instance. 

sizeof 

Answer the number of bytes in the data section of any instance. 

instance creation 

new 

Return a new instance of the receiver. 

Rationale 

Since all external data classes either do or do not contain pointers, the 
ExternalData hierarchy splits at this level into ExternalBinaryData and 
ExternalPointerData. ExternalBinaryData is an abstract class which implements 
protocol common to all of its concrete subclasses which, by definition, do not contain 
pointers. Inherited protocol designated as subclass responsibility is implemented in 
this class. All subclasses of the ExternalBinaryData branch of the external data 
hierarchy have a class instance variable, sizelnBytes, defined here as the number 
of bytes in the data area of all instances of a subclass. 

Discussion 

Naming Conventions for Subclasses' Class Variables 

Most of the time (exceptions are explained below), there is one class variable for 
each named field in the external data structure represented by a Smalltalk class. 
Each external data structure class variable holds the offset of a single field in the 
structure. The name of a class variable is constructed from a field name, stripped of 
its prefix, with the string 'Datalndex' appended. The bytes of a named field in an 
external structure reside in the byte array starting at the offset indicated by the class 
variable for the field. For example, in the following figure, the bytes of a field called 
"foo" would begin at position FooDatalndex in the data area (byte array) of the 
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Phoney object representing the structure with "foo" in it. See Figure 1 for a simple 
example. 



c 


Smalltalk 


struct phoney { 

long foo; 
char bar; 
} sample; 


1 1 1 1 1 1 #a 1 (dataArea, a ByteArray, 
A i^ of instance of Phoriey) 

FooDatalndex (1) 

BarDatalndex (5) 


sample.foo = 1 ; 
sample.bar = 'a'; 


data In the "foo" field is accessed by the message foo 
data in the "bar" field is accessed by the message bar 
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An example will help to illustrate the class variables naming convention. The 
following is the definition of the C structure which the Rusage class represents. 



/* user time used */ 
/* system time used */ 

/* integral shared memory size */ 

/* integral unshared data size */ 

/* integral unshared stack size */ 

/♦ page reclaims ♦/ 

/* page faults ♦/ 

/* swaps ♦/ 

/* block input operations */ 

/* block output operations */ 

/* messages sent ♦/ 

/* messages received */ 

/♦ signals received */ 

/* voluntary context switches */ 

/* involuntary ♦/ 



struct rusage { 




struct timeval 


ru_utime; 


struct timeval 


ru_stime; 


long 


ru_maxrss; 


long 


rujxrss; 


long 


rujdrss; 


long 


rujsrss; 


long 


ru_minflt; 


long 


ru_majflt; 


long 


ru_nswap; 


long 


rujnblock; 


long 


ru_oublock; 


long 


ru_msgsnd; 


long 


ru_msgrcv; 


long 


ru_nsignals; 


long 


ru_nvcsw; 


long 


ru_nivcsw; 
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The first two fields of struct rusage are of type struct timeval, defined as follows. 

struct timeval { 

long tv_sec; /* seconds */ 

long tv_usec; /* microseconds */ 
} 

There are fourteen class variables for the Rusage fields with simple data types (all 
the fields of type long). In addition to the fourteen class variables for the simple 
fields of struct rusage, Rusage has class variables for the fields whose data type is 
a structure — rusage fields ru_utime and ru_stime are of type struct timeval. The 
additional variables are named StimeSecDatalndex, StimeUsecDatalndex, 
UtimeSecDatalndex, and UtImeUsecDatalndex. These names are derived from 
the field name in struct rusage and the name of the field in struct timeval. Field 
names are stripped of their prefix, as usual, to arrive at the "structure within a 
structure" class variable names. 

If an external data structure has fields which are not presently used, usually 
indicated by "reserved" in the field comment, the Smalltalk class for the structure 
does not have class variables for the "reserved" fields. 

Naming Conventions for Subclasses' Protocol 

Each concrete subclass of ExternalBinaryData has protocol for accessing the data 
of the structure. Message selectors are the field name, stripped of its prefix. For 
example, sending the message inblock to an instance of Rusage will return the 
value of the rujnblock field. The message sec:, sent to an instance of Timeval, will 
set the value of the tv_sec field to the specified argument. Depending upon whether 
the structure is exclusively filled in by the operating system. Or whether Smalltalk will 
send data to the operating system in the structure, accessing methods are provided 
to access or to access and set the values of fields. In the case of Rusage, protocol 
is provided to only access the field data, not to set the fields, since the purpose of 
the structure is to obtain data from the operating system. Since a Timeval is used 
to send and receive data, protocol is provided to access and set the values of fields. 

When the value of a field is dependent upon the value of another field, no separate 
method is provided to set the value of the dependent field. The method which sets 
the value of the field it depends upon sets the value of the dependent also. This 
pattern of accessing protocol for field values which are dependent upon other fields 
has been followed in the concrete subclasses of FixedSizeExternalPointerData 
and ExternalBinaryData. 
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When a structure field is another structure, separate accessing messages are 
provided for the fields in the imbedded structure. For example, the Rusage method 
stImeSec returns the value of the tv_sec field of the timeval structure addressed by 
the struct rusage ru_stime field. 

Protocol to set the value of a field which is an imbedded structure takes an instance 
of the class representing the imbedded structure as an argument. For example, the 
Itimerval method interval: takes an instance of Timeval as an argument and sets 
the value of the itjnterval field, which is of type struct timeval. 

ExternalBinaryData Class Protocol 

Accessing methods implement inherited protocol to return the numberOfPointers (O 
for all subclasses) and the sizeOf all instances of a subclass, the sizelnBytes class 
instance variable. The pointersSize method exists to parallel the 
ExternalPolnterData method of that name; it returns since no subclasses contain 
pointers. 

Instance creation defines the method new to return an instance with the correct 
number of indexable variables. As an abstract class, you would not send the 
message new to ExternalBinaryData to create an instance of this class. The 
method is implemented here for use in subclasses. Instance creation methods in 
concrete subclasses return an instance of the class with the fields filled, either with 
data obtained via a system call or data supplied as arguments to the instance 
creation message. There is no pattern for subclasses' instance creation protocol — it 
varies according to the common uses of individual structures. 

ExternalBinaryData Instance Protocol 

Accessing has one method, dataArea, which returns the receiver, since all instances 
of subclasses are strictly data (no pointers). Subclasses of the other branch of 
external data, ExternalPolnterData, have an instance variable, dataArea, which is 
returned when the message dataArea is sent to an instance of a subclass. The 
inherited method replaceFrom:to:wlth:startlngAt: is reimplemented; it invokes a 
primitive to perform a memory to memory data copy. 

Conversion has one method which converts a specified range of the receiver from 
bytes to a String and returns the String. The purpose of this method is to convert a 
string as represented in an external language (for example, an array of chars in C) 
to a Smalltalk String. 
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Adding Classes to this Hierarchy 

If you are adding a subclass of ExternalBinaryData and the conventions just 
described are unclear to you, the best idea is to find a structure class similar to the 
structure you are adding and model your class on the similar one. Your new class' 
protocol must include a class initialization method which initializes the class 
variables and sizelnBytes. Remember to execute the Initialize method for the new 
class. 

Related Classes 

Subclasses: 

DisplayState 

Inaddr 

IntegerPointer 

Itimerval 

Ltchars 

Rlimlt 

Rusage 

Sgttyb 

Sockaddrin 

SockaddrUn 

Stat 

Tchars 

Timeval 

TImezone 

Utsname 

Walt 

You might also want to look at ExternalData, the superclass. If you are adding a 
class for a structure with imbedded pointers, read about ExternalPointerData — 
your new class should be a subclass of that class or its subclass, 
FixedSizeExternalPolnterData. 
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Object subclass: #ExternalData 

instance VariableNames: 

class VariableNannes: 'Char Int Long Pointer Short ' 

pooIDictionaries: 

category: 'OS-Parameters' 



Summary 

ExternalData Is an abstract class for defining data structures suitable for 
communicating with non-Smalltalk languages. Translation must occur to change 
Smalltalk objects to the data structure of another language, and vice versa. This 
class reimplements some ByteArray protocol. 

Naming Conventions for Subclasses and Subclass Protocol 

A class is created for each external language structure. A structure with imbedded 
machine pointers is made a subclass of ExternalPointerData. A structure without 
imbedded machine pointers is made a subclass of ExternalBlnaryData. The class 
name is the same as the structure name. For example, the class Sockaddrin 
provides creation and accessing protocol for a C structure of that name. Fields are 
accessed by the names given in the structure, stripped of the prefix. For example, 
in Sockaddrin, the "sinjamily" field is accessed with the message family. Offsets 
into the structure are provided as class variables. 

Class Variables 

Char <lnteger> 

Number of bytes for a C char type. 

Int <lnteger> 

Number of bytes for a C int type. 

Long <lnteger> 

Number of bytes for a C long type. 

Pointer <lnteger> 

Number of bytes for a C pointer type. 

Short <lnteger> 

Number of bytes for a C short type. 
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Instance Methods 

accessing 



at: index 

Answer the value of the indexable field, index, of the receiver's dataArea. 

at: index put: anObject 

Store the value, anObject, in the indexable field, index, of the receiver's 
dataArea. 

dataArea 

Answer the data portion of the receiver. Subclass responsibility. 

doubleWordAt: index put: value 

Set the value of the double word (4 bytes) starting at byte index. 

numberOfPointers 

Return the number of pointers imbedded in the structure represented by 
the receiver. 

replaceFrom: start to: stop with: replacement startingAt: repStart 

This destructively replaces elements from start to stop in the receiver, 
starting at index repStart in the Collection replacement. Answer the 
receiver. No range checks are performed. 

signedlntegerDoubieWordAt: index 

Answer the value of the double word (4 bytes) starting at byte index. Treat 
the value as a 2's complement signed integer. 

signedlntegerWordAt: index 

Answer the value of the word (2 bytes) starting at byte index. Treat the 
value as a 2's complement signed integer. 

sizeof 

Answer the number of bytes in the data section of the receiver. 

unsignedlntegerDoubieWordAt: index 

Answer the value of the double word (4 bytes) starting at byte index. Treat 
the value as an unsigned integer. 

unsignedlntegerWordAt: index 

Answer the value of the word (2 bytes) starting at byte index. Treat the 
value as an unsigned integer. 

wordAt: index put: value 

Set the value of the word (2 bytes) starting at byte index. 
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Class Methods 



class initialization 

initialize 

Initialize the class variables. 

accessing 

numberOfPointers 

Return the number of pointers imbedded in the structure represented by 
the receiver. Subclass responsibility. 

sizeof 

Answer the number of bytes in the data section of any instance. Subclass 
responsibility. 

Rationale 

ExternalData is an abstract class which implements protocol common to all of its 
subclasses. This class and its subclasses were created to provide a mechanism for 
Smalltalk to exchange data with the operating system when making system calls. 

Discussion 

As an abstract class, there is no instance creation protocol in ExternalData. The 
instance and class protocol includes message selectors that will be sent to 
subclasses, not to this class. If you are adding a class that represents an external 
language structure, you should look at the abstract subclasses of ExternalData and 
make your new class a subclass of one of them, not a subclass of this class. 

Class Protocol 

Class initialization has one method which sets the values of the class variables. 

Accessing methods return the number of pointers in the structure, and the number of 
bytes in the dataArea of the structure — implementation of these functions is left to 
a subclass. 

Instance Protocol 

Since the data of an external structure are represented in a Smalltalk object as a 
ByteArray, this class reimplements some ByteArray accessing protocol. 
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Accessing methods return or set the values of indexable fields in the dataArea of the 
receiver. There are different accessing methods for the different sizes of data — 
one byte, two bytes, or four bytes — and for signed or unsigned integers. One 
method, replaceFrom:to:With:startlngAt:, replaces a chunk of data in the receiver. 
The work of two methods, dataArea and sizeof, is ultimately done by a subclass. 



Related Classes 

Subclasses: 

ExternalBinaryData 
ExternalPointerData 
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ExternalData subclass: #ExternalPointerData 

instanceVariableNames: 'dataArea pointers 

class VariableNames: 

poolDictionaries: 

category: 'OS-Parameters' 



Summary 

ExternalPointerData is an abstract class for a non-Smalltalk data structure 
containing machine pointers. It holds the binary data for the non-Smalltalk data 
structure and an array of Smalltalk objects whose machine addresses will be 
inserted into the binary data. The addresses are inserted by the interpreter when 
certain primitives are invoked. 

Instance Variables 

dataArea <ByteArray> 

Binary data of a non-Smalltalk data structure, 

pointers <Array> 

Pairs offsets into the binary data portion (dataArea) with objects. 



Instance Methods 

accessing 



dataArea 

Return the dataArea of the receiver. 

dataArea: aByteArray 

Update the dataArea of the receiver with aByteArray. 

dataArea: aByteArray pointers: anArray 

Update the dataArea of the receiver with aByteArray and the pointers with 
anArray. 

numberOfPointers 

Return the number of pointers imbedded in the structure represented by 
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the receiver. 

pointers 

Return the pointers of the receiver. 

pointers: anArray 

Update the pointers of the receiver. 

sizeof 

Return the size of the data area in bytes. 



copying 



copy 

Return a copy of the receiver. Insure that pointers of the copy reference 
the same objects as the pointers of the receiver. 

Rationale 

Since all external data classes either do or do not contain pointers, the 
ExternalData hierarchy splits at this level into ExternalBinaryData and 
ExternalPointerData. ExternalPointerData is an abstract class which implements 
protocol common to all of Its concrete subclasses which, by definition, contain one 
or more pointers. Inherited protocol designated as subclass responsibility is 
implemented in this class. 

Discussion 

Naming Conventions for Subclasses' Class Variables 

The name of a class variable is constructed from a field name, stripped of its prefix, 
with one of the following strings appended, as appropriate: 'Datalndex' or 
'Pointerlndex'. Fields without pointers have one class variable, <field- 
name>Datalndex. For fields with a data type having imbedded machine pointers, 
two class variables are created: 

• one for the offset of the binary data, and 

• one for the index of the pointer to that field, with respect to other pointers in the 
structure. 

The <field-name>Datalndex indicates the index of the first byte of the data in the 
dataArea. The <field-name>Pointerlndex is used in accessing protocol to access or 
set the value of a pointer field in pointers. 

An example will help to illustrate the naming convention for class variables. The 
following is the definition of the structure which the Msghdr class represents. 
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struct msghdr { 




caddr_t 


msg_name; 


int 


msg_namelen; 


struct iovec 


♦msgjov; 


int 


msgjovien; 


caddr t 


msg_accrights; 


int 


msg_accrightslen; 



/* optional address */ 
/* size of address */ 
/* scatter/gather array */ 
/♦ # elements in msgjov */ 
/♦ access rights sent/received ♦/ 



} 



The third field, *msgJov, is a pointer to a struct iovec, which is defined as follows. 

struct iovec { 

caddr_t iov_base; 

int iovjen; 

} 



There are six fields in struct msghdr. The first, third and fifth fields are pointer types 
(caddr_t is defined as a pointer to a char). The class variables for the pointer fields 
are shown in the following table. 



Pointer Fields' Class Variables 



field name 



class variables 



contents 



msg_name NameDatalndex 



NamePointerlndex 



♦msgjov lovDatalndex 



lovPointerlndex 



msg_accrights AccrightsDatalndex 



offset (1) of the first 
byte of msgjiame data 
in dataArea 
index (1) of this 
pointer with respect to 
other pointers in the 
structure 

offset (9) of the first 
byte of *msgJov data 
in dataArea 
index (2) of this 
pointer with respect to 
other pointers in the 
structure 

offset (17) of the first 
byte of msg_accrights 
data in dataArea 
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AccrlghtsPointerlndex index (3) of this 

pointer with respect to 
other pointers in the 
structure 

Msghdr has three other class variables for the three fields which are not pointers. 



Other Fields' Class Variables 

field name class variable contents (offset) 

msg_namelen NamelenDatalndex 5 
msgjovlen lovlenDatalndex 13 
msg_accrightslen AccrlghtsienPatalndex 21 

If an external data structure has fields which are not presently used, usually 
indicated by "reserved" in the field comment, the Smalltalk class for the structure 
does ?iot have class variables for the "reserved" fields. 

dataArea and pointers Instance Variables 

This section describes the two instance variables, dataArea and pointers, provides 
an illustration of their relationship, and gives details of the elements of the value- 
offset pairs in pointers. 

The dataArea instance variable is a ByteArray of the data in the structure. The 
index of the first byte of each structure field in the dataArea is indicated by the 
<field-name>Datalndex class variable for the field. A pointer field's "Datalndex" 
class variable is also the second element of the field's value-offset pair in the 
pointers array. 

The pointer array, pointers, is an instance of Array which stores pairs of elements 
(i.e., "anArray at: 1:" together with "anArray at: 2" make up a "pair"). For each 
pointer in a structure, there is one pair (two elements) in pointers. For example, 
since a Msghdr contains three pointers, its pointers array has three pairs — six 
elements. 

The figure below depicts an instance of Msghdr to show the value of its instance 
variables. The code preceding the figure is an example that creates the objects 
needed for the figure. 

anlovecArray <— StructurcArray new: 2 class: lovec. 
anlovccArray at: 1 put: (lovcc base: 'first'). 
anlovecArray at: 2 put: (lovec base: 'second'). 
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In the figure, the dataArea has space for three machine addresses which will be 
filled by a system call or display primitive. The dotted lines indicate that the 
addresses filled in by the primitive will refer to objects in the pointers array. 

Value 

The first element of a pair (the odd indexed element) contains a Smalltalk object 
which is conceptually referenced by the field of the non-Smalltalk structure. This 
element is called the value. If the function of the system call is to return data from 
the external language structure to Smalltalk, then the appropriate value locations in 
pointers will be changed after the system call. 

Offset 

The second element of a pair (the even indexed element) is called the offset. It 
contains the index into the dataArea, a ByteArray, where the first byte of the 
pointer (i.e., an address) is stored. Indices in the dataArea are counted from 1 . 
The offset identifies the position where a reference to a Smalltalk object is 
considered to virtually exist. The space reserved for addresses in dataArea Is filled 
in by a display or system call primitive; however, after the call is completed the 
addresses may no longer be valid for the Smalltalk objects they referenced when 
the call was invoked. 

Primitive Action on dataArea 

If the offset Is nil, indicating an unused map pair, the associated value Is ignored. 
This might be useful for representing 'union' types in which some fields must be 
empty. If the value is the object nil, the primitive will replace the associated field in 
the dataArea with the binary value 0. If the value is a Smalllnteger or a 4-byte 
LargePosltlvelnteger or LargeNegatlvelnteger, the primitive will replace the 
associated field in the dataArea with the machine representation of the integer 
value. If the value is an ExternalBlnaryData object (or a variableByte or 
variableWord class without instance variables), then the field is replaced with the 
machine address of the data part of the object. Otherwise, the value is assumed to 
be an ExternalPointerData object; the associated field in the dataArea is replaced 
with the address of the data part of the ExternalPointerData object and above rules 
are recursively applied. When the recursion is completed, all pointers in the 
dataArea will contain valid addresses and the pointers in the dataArea of each 
referenced object will also contain valid addresses. This allows a structure to contain 
pointers to other structures. 

The following table summarizes the possible meanings of the pointers array. 
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Offset Value Primitive Action on dataArea 

nil anything value is ignored 

X nil at X store the machine integer whose value is 


X Smalllnteger at x store machine integer 

X 4-byte LargePositivelnteger at x store machine integer 

X 4-byte LargeNegativelnteger at x store machine integer 

X ExternalBinaryData at x store machine address of data portion 

X ExternalPointerData at x store machine address of data portion 

and recurse 

(x is an integer) 

Naming Conventions for Subclasses' Protocol 

Each concrete subclass of ExternalPointerData has protocol for accessing the data 
of the structure. Message selectors are the field name, stripped of its prefix. For 
example, sending the message accrights to an instance of Msghdr will return the 
value of the msg_accrights field. The message accrights:, sent to an instance of 
Msghdr, will set the value of the msg_accrights field to the specified argument. 
Since the value of the msg_accrightslen field is dependent upon the length of the 
string in msg_accrights, there is no method provided to set the value of 
msg_accrightslen. The accrights: method sets the value of both fields. This 
pattern of accessing protocol for field values which are dependent upon other fields 
has been followed in the concrete subclasses of FIxedSlzeExternalPolnterData 
and ExternalBinaryData. 

Depending upon whether the structure is exclusively filled in by the operating 
system, or whether Smalltalk will send data to the operating system in the structure, 
accessing methods are provided to access or to access and set the values of fields. 

Protocol to set the value of a field which is an imbedded structure takes an instance 
of the class representing the imbedded structure as an argument. At present there 
are no subclasses of FIxedSlzeExternalPolnterData which represent a structure 
with an imbedded structure. 

ExternalPointerData Instance Protocol 

This protocol is present to be inherited by concrete subclasses. Since this is an 
abstract class, there is no instance creation protocol and no messages should be 
sent to this class. 

Accessing has one method, dataArea, which returns the dataArea instance variable, 
and another method to set the dataArea. There are two methods to access and set 
the value of the pointers instance variable. Another method, dataArea:pointers:, 
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sets the value of both instance variables. The numberOfPoInters method returns 
the number of pointers in the structure, and the sizeOf method answers the size of 
the dataArea in bytes. 

Copying has one method which returns a copy of the receiver. 

Related Classes 

Subclasses: 

FixedSizeExternalPointerData 

PointerArray 

StructureArray 

You might also want to look at the superclass, ExternalData, and the parallel 
abstract class for structures which do not contain pointers, ExternalBlnaryData. 
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FileStream subclass: #FileDirectory 

instance VariableNames: 

class VariableNames: 

poolDictionaries: 

category: 'OS-Streams' 



Summary 

Instances of FileDirectory are a special kind of FileStream that represent 
directories. Tlie instance variable name identifies the directory instances refer to. 
Directories can be viewed as a collection of files — enumerating protocol is 
provided. Instances of FileDirectory can be found in dictionaries, or another 
FileDirectory, though often this is implicit. 

Inherited Instance Variables 

name <String> 

This inherited instance variable contains a relative or absolute path 
specifying this directory. Relative paths are relative to Disk. 

directory <nil> 

This inherited instance variable is not used. 

Instance Methods 

accessing 

completePathname 

Answer the complete path name of the receiver, starting with the root 
directory. A trailing path name separator is considered part of a directory 
name even if not explicitly stored. 

contents 

Answer the names of all files in this directory. 

directoryName 

Answer the name of the receiver. 

fuliName 

Answer the full path name of the receiver, relative to Disk if appropriate. A 
trailing path name separator is considered part of a directory name even if 
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not explicitly stored. 

versionNumbers 

Answer true if version numbers are supported. 

adding 

addKey: aFileName 

Create a new file whose name is aFileName. The method newFile: 
produces an error if the file already exists. 

enumerating 

do: aBlock 

Sequence over all possible files (or directories) in the receiver, evaluating 
aBlock for each one. 

fllesMatching: patternString 

Answer an Array of the names of files (or directories) that match 
patternString. 

namesDo: aBlock 

Sequence over all possible file (or directory) names in the receiver, 
evaluating aBlock for each one. A collection of file names is created so 
that the operating system will not dynamically increase the directory size 
when backup files are created. 

file accessing 

checkName: aFileName fixErrors: fixErrorsBoolean 
Check aFileName for validity as a file in this directory. 

directoryNamed: aString 

Answer an instance of myself whose name is aString. Answer Disk if 
aString matches Disk. 

file: aFileName 

Answer a FileStream on an old or new file whose name is aFileName. 

fileClass 

Answer the proper class whose instances represent files in the receiver. 
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isLegalFlleName: aString 

Answer whether aString is a legal file name. 

isLegalOldFiieName: aString 

Answer whether aString is a legal file name and if the file exists in the 
receiver. 

newDlrectory: aDirectoryName 

Answer a FileDirectory on a new directory whose name is aDirectoryName; 
notify If the argument is not a new file name. 

newFlIe: aFileName 

Answer a FileStream on a new file whose name is aFileName; notify if the 
argument is not a new file name. 

oldFile: aFileName 

Answer a FileStream on an old file whose name is aFileName; notify if the 
argument is not an old name. 

oldWriteOnlyFile: aFileName 

Answer a FileStream on an old file (write only) whose name is aFileName; 
notify if the argument is not an old name. 

rename: aFlle newName: newName 

Rename the file, aFile, to have the name newName; notify if a file by the 
name, newName, already exists. 



file copying 



append: aFileNamel to: aFileName2 

Append the contents of a file whose name is aFileNamel to the end of a 
file whose name is aFileName2. 

copy: aFileNamel to: aFileName2 

Copy the contents of a file whose name is aFileNamel to a file whose 
name is aFileName2. 



removing 



removeKey: aFileName 

Remove the file whose name is aFileName; notify if not found. 

removeKey: aFileName IfAbsent: absentBlock 

Remove the file whose name is aFileName; answer the result of evaluating 
absentBlock If not found. 
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testing 

includesKey: aFileName 

Answer whether a file or directory whose name is aFileName is included in 
the receiver. 

is Empty 

Answer whether there are any files in the receiver. 

statusOf: aFileName 

Answer the status of aFileName without opening it. 

xerox file compatability 

fIndKey: aFileName 

Answer an instance of the file class which represents a file with the name 
aFileName. 



Class Methods 



instance creation 

currentDirectory 

Answer an instance of me representing the current directory. 

directoryFromName: fileName sotFileName: aBlock 

Answer the file directory implied from the designator fileName. This 
directory contains the designated file. Evaluate the block with only the file 
name portion of the designator. 

directoryNamed: aString 

Answer an instance of me whose name is aString. Answer Disk if aString 
matches Disk. 

fileNamed: aFileName 

Not appropriate for a FileDirectory. 



Rationale 



FileDirectory is a representation of a directory on the disk. It provides protocol for 
looking at the files in a directory. 



Discussion 



Disk is a global variable, an instance of FileDirectory. In the standard image Disk 
is set to ".", the current directory. This means that Disk "floats" to whatever 
directory you are in when you invoke Smalltalk. The Smalltalk home directory 
concept is used throughout file creation and referencing methods. There is example 
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code in the System Workspace for changing the value of Disk. 

Class Protocol 

Instance creation provides several ways to create an instance of FileDirectory. 
Instances can be created from the current directory, from the directory implied in a 
full path name, or by naming a directory. The inherited flleNamed: method is 
intercepted. 

Instance Protocol 

Accessing methods answer the directory name, answer a collection of the file names 
in the receiver, answer the name instance variable, and answer false to indicate that 
version numbers are not supported. Complete path means begin at root and fully 
specify the path. Full name means the name relative to Disk if Disk is part of the 
path, or the complete path relative to root (/) if Disk is not in the file's path. 

Adding has one method which creates a new file with the specified name. 

Enumerating has two methods which evaluate a block for all entries in the directory 
and a method, fiiesMatching:, that returns an array of file names matching an 
ambiguous file name — the ambiguous name provides the ability to use wildcard 
characters such as # or ♦. 

File accessing methods perform many types of functions. You can check for invalid 
characters (less than ASCII 33 or greater than ASCI1 126) in a file name and, 
optionally, remove the illegal characters. Two methods return true if a specified file 
name does not contain illegal characters; in addition, one of them checks that the 
file exists before answering true. One method answers the appropriate class of 
Smalltalk objects representing files in these directory objects — this allows some 
independence for FileDirectory. 

Several file accessing methods return instances of this class and FileStream. You 
can choose among methods that check whether a file exists before creating a 
stream on it, that further specifies that the stream be write-only, or one that creates 
the stream without testing for the file's existence. This message category also has 
methods to create a new file or directory and rename an existing file. 

If you don't want to always fully qualify the path of a file (or files) that you access 
frequently, you can use the following method. 

• Create an instance of FileDirectory on the directory which contains the file(s). 
Keep the instance of FileDirectory in your image. 
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• Send a message to the FileDlrectory to create a FlleStream on the file when 
you want to access It (e.g., aPileDirectory oldFile: nameOfFile). The 
FlleStream will be created relative to the path of the FileDlrectory. 

The above approach can be used for any directories you access often — just keep 
the instances of FileDlrectory in your image. 

File copying contains one method which appends the contents of a specified file to 
another file and one method which copies the contents of one file to another file. 

Removing methods let you remove a disk file from the directory and, optionally, 
specify a block to be evaluated if the disk file does not exist. 

Testing methods check whether a disk file exists, whether the directory is empty, and 
answer an instance of the file status class for your operating system. 

The single xerox file compatibility method, fIndKey: calls flleClass and returns an 
instance of the class that method specifies. This method is retained for backward 
compatibility. 

Examples 

The following example can be executed in a workspace. If you do so, you might 
want to change the ambiguous file name to yield files you actually want to file in. 
For ease of use, a file list is better for filing in one file at a time. If you want a group 
of files to file in, the example code is a fast way to do it. 

dir <- Disk directoiyNamed: '/usr/lib/smalltalk/filein'. 
(dir filesMatching: 'a*.st') do: 

[:eachFile | (dir file: eachPile) fileln] 

The global FileDlrectory, Disk, is sent an instance creation message with the full 
path name as an argument. The instance Is assigned to dir. An enumerating 
message, filesMatching:, is sent to dir with an ambiguous file name as the 
argument. For each file whose name begins with a and has the extension .st, an 
instance of FileStream is created. A FileDlrectory ^/e acce^^m^ message, file:, 
creates the instances. Each instance is sent the message fileln, which incorporates 
the contents of the file into the image. 

Related Classes 

You are probably familiar with the results of some of this class' protocol, because 
FileDlrectory is used in FileLlsts. Look in your System Workspace under "Create 
File System" for example code using FileDlrectory and FlleStream. 
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ExternalStream subclass: #FileStream 


instance VariableNames: 


'name directory mode fileDescriptor filePosition 




fileMode ' 


classVariableNames: 


'OpenFileStreams ' 


poolDictionaries: 


" 


category: 


'OS-Streams' 



Summary 

Instances of FlleStream represent stream interfaces to mass storage files. Read 
and write data are buffered to minimize operating system calls. The buffer size is 
arbitrary; it need not reflect the physical disk block size. The buffer is either a 
ByteArray or a String depending on Smalltalk's view of the data. Characters and 
bytes are stored identically in mass storage. 

Instance Variables 

directory <FileDirectory> 

This instance variable represents the directory containing the file, nil if 
unknown. 

fileDescriptor <Small Integers 

This instance variable represents the file identifier assigned by the 
operating system, or nil if the file is not open. 

filelVIode <Symbol> 

This instance variable indicates the current permissions (#ReadOnly, 
#ReadWrite, or #WriteOnly) of this fileDescriptor. The value of fileMode 
reflects the last file activity in the file (e.g., #ReadWrite if the file was written 
to and then read). It can be #WriteOnly if FileStream opens the file write 
only or if the file is created by methods in this class. 

filePosition <lnteger> 

This instance variable indicates the position of the operating system file 
pointer in the file. 

mode <Symbol> 

This instance variable indicates the intended reading/writing mode 
(#ReadOnly or #ReadWrite), nil if unknown. 
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name <String> 

This instance variable identifies the file within a directory. 

Inherited Instance Variables 

collection <ByteArray> or <String> 

This inherited instance variable is the buffer for either reading or writing 
data. 

position <Smalllnteger> 

This inherited instance variable represents the current position in the 
buffer. 

readLlmit <Smalllnteger> 

This inherited instance variable represents the maximum position before 
the buffer is filled. When the buffer is empty, both position and readLimit 
are 0. 

wrlteLlmit <Smalllnteger> 

This inherited instance variable represents the maximum position before 
buffer is flushed. 

Class Variables 

OpenFileStreams<OrderedCollection> 

All open FileStreams are listed here. 

Instance Methods 

accessing 



contentsOfEntireFile 

Read all of the contents of the receiver, 

next 

Answer the next character (or byte) from the receiver. Answer nil if at the 
end of the receiver's file. 

next: aninteger 

Answer the next aninteger bytes from the receiver. 
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next: aninteger into: aCollection 

Copy the next aninteger bytes from the receiver into aCollection. If 
aCollection has word-sized elements, each element is filled with byte-sized 
numbers. Answer aCollection. 

nextPut: aCharacterOrByte 

Place the character or byte in the buffer and return that character. If the 
buffer is full, flush the buffer. If the file is not writable, make it writable. Call 
nextPut: again. 

nextPutAII: aCollection 

Write the elements of aCollection onto the receiver. If aCollection will fit in 
the receiver's buffer then buffer it, otherwise, write it directly to the 
receiver's file. If aCollection is not a String or ByteArray (a Set of 
Characters, for example) write each of its elements individually. 

nextPutAII: aCollection startingAt: startlndex 

Append the elements of aCollection, if it is of an appropriate type, onto the 
receiver starting at startlndex. Answer aCollection. 

nextPutAII: aCollection startingAt: startlndex to: stoplndex 

Append the elements of aCollection, if it is of an appropriate type, onto the 
receiver starting at startlndex and stopping at stoplndex. Answer 
aCollection. 

size 

Answer the size of the receiver's file in characters (or bytes). 

converting 

asFileDirectory 

Return the file directory representing the receiver. 



copying 



copy 

Answer a copy of the file with a nil file descriptor. 
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editing 
edit 



Create and schedule a FileModel on the contents of the receiver. The label 
of the view is the name of the receiver. 



file accessing 



description 

Answer a String describing the receiver's file. 

directory 

Answer the directory that contains the receiver. 

fiieName 

Answer the name of the receiver's file. 

fulIName 

Answer the full path name of the file represented by the receiver. 

name 

Answer the name of the receiver's file. 

remove 

Remove the receiver from its parent directory. Discard the mass storage 
associated with the receiver. 

rename: newFileName 

Change the name of the receiver to newFileName. 



file modes 



binary 

Set the receiver's file to be buffered in binary mode. Copy any already 
buffered data to the new buffer, a ByteArray. 

readonly 

The receiver will be used for reading only. 

readWrite 

The receiver will be used for reading and writing. Do not backup on first 
write. 
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readWriteShorten 

Same as readWrite. We don't support the shorten operation, so senders 
must explicitly close to truncate the file at the current position. 

text 

Set the receiver's file to be buffered in text mode. Copy any already 
buffered data to the new buffer, a String. 

writeShorten 

Same as readWrite. We don't support writeOnly, or the shorten operation. 
Senders must explicitly close to truncate the file at the current position. 



file status 



close 

Disassociate the receiver with its file in mass storage. If write data are 
buffered, flush the buffer. If read data are buffered, discard the data and 
adjust filePosition to reflect the loss. 

fill Fill the read buffer, collection, with data from mass storage. Flush the write 
buffer if required. 

flush 

Flush the output buffer, collection, to mass storage. Do nothing if the buffer 
is empty or is not an output buffer. 

shorten 

This operation is preserved for historical reasons. The structure of the 
existing file system does not encourage use of this file truncating method. 
The native use of backup files is suggested instead. 



file testing 



exists 

Answer whether the file represented by the receiver exists in mass storage. 

isBackup 

Return true if the name of the file associated with this FileStream follows 
the convention for naming backup files. 
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isBinary 

Answer whether the receiver is reading binary bytes (as opposed to 
characters), 

IsDirectory 

Answer true if the receiver is a directory. 

isOpen 

Answer whether the receiver is open, that is, if the file represented by the 
receiver has been located and a file descriptor assigned. 

isReadable 

Answer whether it is possible to read from the receiver. 

isStandard 

Answer true if the receiver represents one of the standard descriptors — 
in, out, or error. 

isText 

Answer whether the receiver is reading characters (as opposed to binary 
bytes). 

isWritable 

Answer whether it is possible to write on the receiver. 

fileln-Out 

fileln 

Guarantee fileStream is readonly before fileln for efficiency and to 
eliminate remote sharing conflicts. 

fileOutChanges 

Append to the receiver a description of all system changes. 

printOutChanges 

Print to the receiver a human-readable description of all system changes. 

nonhomogeneous positioning 

padTo: bsize 

Skip to next boundary of bsize characters, and answer how many 
characters were skipped. 

padTo: bsize put: aCharacterOrByte 

Pad using the argument, aCharacterOrByte, to the next boundary of bsize 
characters, and answer how many characters were written. 
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positioning 



position 

Answer the position of the receiver in characters (or bytes) from its 
beginning. Compute this from the file's physical position considering any 
read ahead (reflected in readLimit) and the current position in the buffer. 

position: aninteger 

Position the receiver to start reading (or writing) at an offset of aninteger 
characters (or bytes) from the beginning of the file. Flush buffered output; 
discard (wastefully) buffered input. Position the receiver's file, if open. 

reset 

Set position to beginning of file. 

setToEnd 

Set position to end of file. 

sl<ip: byteCount 

Advance position by byteCount. A negative byteCount will backspace. 
Preserve buffered read data if possible; always flush buffered write data. 

printing 

printOn: aStream 

if the receiver is a file in the Disk directory, print with its path name relative 
to Disk. Otherwise, print its full path name. 

testing 

atEnd 

Answer true if current position is >= end of file position. Fill the input buffer 
if necessary to access the next character. 

xerox file compatability 

asFiieStream 

Answer the file stream representing the receiver. 

file Answer the file representing the receiver. 

Class Methods 



class initialization 
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initialize 

Make a new collection for holding open files. 

external references 

closeExternalReferences 

Close all open instances of the receiver and its subclasses. Use the 
bypassClose message to bypass the Smalltalk file tracking system. Only 
subtasks (child tasks) should execute this method. 

release ExternaiReferences 

Close all open instances of the receiver and its subclasses. 

instance creation 

fileNamed: aString 

Answer a FileStream on an old or new file designated by aString. Do not 
(yet) try to open. 

fileNamed: aString in: aDirectory 

Answer a FileStream on an old or new file designated by aString and 
located in aDirectory. 

newFiieNamed: aString 

Answer a FileStream on the new file designated by aString. Go ahead and 
create the file to be sure we can. 

newFiieNamed: aString in: aDirectory 

Answer a FileStream on the new file designated by aString and located in 
aDirectory. Go ahead and create the file to be sure we can. 

oldFiieNamed: aString 

Answer a FileStream on the old file designated by aString. Go ahead and 
open the file to be sure we can. 

OldFiieNamed: aString in: aDirectory 

Answer a FileStream on the old file designated by aString and located in 
aDirectory. Go ahead and open the file to be sure we can. 

oldWriteOniyFileNamed: aString 

Answer a FileStream on the old file designated by aString. Go ahead and 
open the file for writing to be sure we can. 

OldWriteOniyFileNamed: aString in: aDirectory 

Answer a FileStream on the old file designated by aString and located in 
aDirectory. Go ahead and open the file for writing to be sure we can. 



72 



FileStream os-streams 



Rationale 

FileStream provides a buffered streaming interface to mass storage files. The 
interface keeps the number of system calls to access files in the operating system to 
a minimum. It reopens files automatically (sources and changes files after a 
snapshot, for example). FlleStreams are positionable, unlike pipe streams. 

Discussion 

Class Protocol 

Class initialization contains the Initialize method to assign values to the class 
variables. It would be used when you are working with a different operating system, 
for example, or want to change the size of the buffer. 

External references methods enable you to close all open file streams or the streams 
with the file descriptors of stdin, stdout, and stderr. The method 
closeExternalReferences should only be sent by instances of Subtask to bypass 
the file tracking system and close all open file streams. It is important to remember 
that file descriptors are a limited resource, so file streams should be closed when 
they are no longer needed. Closing them releases their file descriptor for use in a 
new instance of FileStream or another object that requires an operating system file 
descriptor. The instance of FileStream will still exist after it is closed, and it can be 
reopened to the same state it was in when it was closed (i.e., at the same 
filePosition with the same mode and fileMode). 

Instance creation methods return an instance of a stream interface to existing files 
and new files. You have the option of using a message beginning 'file' which 
creates the stream without opening its associated file; 'file' methods automatically 
create backup copies of existing files. 'New file' methods determine whether the 
specified file exists; if it does, a notifier displays to give you the option to "proceed" 
to rename the existing file as a backup. 'Old file' methods determine whether the 
specified file exists; if it does, a notifier displays to give you the option to "proceed" 
to create the file. Two methods will open an old file for writing only. They determine 
whether the specified file exists; if it does, a notifier displays to give you the option to 
"proceed" to create the file. 

Instance Protocol 

Some of the contents of the accessing message category is determined by what 
FileStream inherits from the Stream hierarchy. These methods are necessary to 
appropriately reimplement certain methods for this class. Accessing methods read 
and return the entire contents of a file, return the next one or more characters or 
bytes in a file, write one or more characters or bytes to the file, and return the 
effective size of the file in mass storage, were you to close the file at that point. The 
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method size includes data in the buffer which would be written to the file via flush if 
you sent the close message when the file was open for writing. 

The converting method returns an instance of FileDlrectory with the complete path 
name of the receiver. 

The editing method creates a view containing the file contents for editing. 

File accessing methods return information about the file obtained from instance 
variables or from a system call. FullName returns the full path of the receiver's 
directory concatenated with the receiver's name or a name relative to Disk. You 
can also remove or rename a file. 

File modes methods allow you to set the mode instance variable to #ReadWrite or 
#ReadOnly. The method binary replaces the collection String with a ByteArray . 
The method text does the inverse of binary. Two 'shorten' methods call readWrlte 
because the shorten operation is not supported. To shorten a file you must close it 
when the file is at the desired position. 

File status methods close a file after flushing the buffer, fill the buffer for reading, 
flush the write data in the buffer to the file, and shorten the file. The shorten 
method is retained for backward compatibility — its use is not recommended. 

File testing methods answer whether a file exists in mass storage, and returns true or 
false for the following file attributes: is a backup file, is binary, is text, is open, is 
readable, is writable, is a directory, and is a standard stream (in, out, or error known 
by file descriptors 0, 1 , and 2). 

Fileln-Out methods incorporate the contents of an external file into the image, and 
enable you to file out or print out changes from the current project. 

Nonhomogeneous positioning methods implement the inherited methods of the same 
name. The methods pad the file to a specified boundary with a specified 
character/byte or skip over characters or bytes in the file to the next specified 
boundary. This message category name is used for compatibility with protocol 
inherited from ExternalStream, although nonhomogeneous does not apply here. 

Positioning methods answer the current location of the last character/byte 
conceptually read or written (buffered data are counted) or set the file pointer. The 
file pointer can also be set to the beginning or end of the file. The method skip: 
moves the FlleStream pointer forward or backward and, if necessary, moves the 
operating system file pointer also. The position: method sets the file pointer to the 
specified location relative to the beginning of the file. 
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The following diagram describes the relationship of positions and the FileStream 
buffer. The instance variable position denotes the position within the buffer. The 
instance variable filePosltlon denotes the operating system file pointer associated 
with the file descriptor. Sending the message position returns the position the 
application thinks it should be at, taking into account unread data in the buffer. The 
instance variable readLimit describes the size of the buffer. 



Reiation of Position to the Buffer and the File in Mass Storage 



I — position >I 

self position >| 



filefilefilefilefilefilefilefilefilefileBUF-BUF-BUF-BUF-BUF-BUFfilefilefilefilefilefile 

I filePosition ^>| 

I — readLimit >| 



Printing has one method that prints a representation of the instance on a stream. 
The output would resemble 'a FileStream on 'testFile". The menu selection 
"printit" calls printOn:. 

Testing has one method that answers whether the end-of-file has been reached. 

Xerox file compatibility methods return the receiver. They are present for 
compatibility with earlier implementations which distinguished between files and file 
streams. 

Examples 

The following code can be executed in a workspace. 

f <- Disk file: 'testFile'. 

fnextPutSA. 

f space. 

f nextPutAlI: 'file for reading '. 

fcr. 

f tab; nextPutAll: 'and writing'; cr. 

f reset. 

first<— f next. 

all <- f contentsOfEntirePile. 

Transcript cr; show: all. 
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Disk removeKey: 'testFile'. 

First, Xhefile accessing message file: is sent to the global FileDlrectory, Disk. An 
instance of FileStream on 'testFile' is created and assigned to/. Accessing 
message nextPut: writes tlie character $A and nextPutAII: writes the string to 
'testFile' via/(actually, the data are buffered and written to the file before it is 
closed). WriteStream character writing messages are used to put a space, a tab, 
and a carriage return in the file. The message reset sets the file pointer to the 
beginning of the file. Accessing messages next and contentsOfEntireFile return a 
character and the contents of the entire file, respectively. The entire file contents, 
all, are displayed in the System Transcript. Finally, 'testFile', is removed from the 
global FileDirectory, Disk. The output in the System Transcript looks like this: 

A file for reading 
and writing 

In the System Workspace under "Create File System" are several examples of 
FileStream and FileDirectory being used by the system. In a workspace you can 
execute SourceFiles inspect and see the array of two FileStreams on the 
sources file and changes file. You can further inspect the elements of the array to 
see the values of their instance variables. 

Related Classes 

Subclasses: 

FileDirectory 

Other classes of interest are 

• the PIpeStream hierarchy, and 

• ExternalStream, the superclass, has useful methods for accessing different 
data types in nonhomogeneous accessing. 
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ExternalPointerData subclass: #FixedSi2eExternalPointerData 

instanceVariableNames: 

class VariableNames: 

poolDictionaries: 

category: 'OS-Parameters' 



Summary 

FixedSizeExternalPointerData is an abstract class for a non-Smalltalk data 
structure containing machine pointers. Eacli subclass defines a particular data 
structure wliose size is fixed. Tlie concrete classes representing non-Smalltalk data 
structures are used to pass information between Smalltalk and the operating 
system, for example, when making system calls. 

Instance Methods 

accessing 

numberOfPolnters 

Return the number of pointers imbedded in the structure represented by 
the receiver. 

poIntersSize 

Answer the size of the pointers array of the receiver. 



FixedSizeExternalPointerData class 

instanceVariableNames: 'sizelnBytes prototype ' 



FixedSizeExternalPointerData class — Instance Variables 

sizelnBytes <lnteger> 

The size of the structure in bytes. 

prototype <aSubclass> 

An instance of the concrete subclass which has the pointers array 
initialized. 
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Class Methods 



accessing 

numberOfPointers 

Return the number of pointers imbedded in the structure represented by 
the receiver. 

pointersSize 

Answer the size of the pointers array. 

sizeof 

Answer the number of bytes in the data section of any instance. 

instance creation 

new 

Return a new instance of the receiver. 

Rationale 

Since all external data classes either do or do not contain pointers, the 
ExternalData hierarchy splits into ExternalBinaryData and ExternalPointerData. 
FixedSizeExternalPointerData, a subclass of ExternalPointerData, is an abstract 
class which implements protocol common to all of its concrete subclasses which, by 
definition, contain pointers and are a fixed size. Objects which are not a fixed size 
but contain pointers, such as an array of pointers or an array of structures which may 
contain pointers, are direct subclasses of ExternalPointerData. 

Inherited protocol designated as subclass responsibility by ExternalData is 
implemented. All subclasses of this branch of the external data hierarchy have two 
class instance variables. SIzelnBytes is defined here as the number of bytes in the 
data area of all instances of a subclass. Prototype is defined here as an instance 
of a subclass with its pointers array initialized. 

Discussion 

You will find it helpful to read the "Discussion" under ExternalPointerData for an 
explanation of the instance and class variables of concrete subclasses of this class. 

Class Protocol 

This protocol is present to be inherited by concrete subclasses. Since this is an 
abstract class, there is no instance creation protocol and no messages should be 
sent to this class. 
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Accessing methods answer the number of pointers in the structure, the number of 
bytes of data in the structure, and the number of elements in pointers. 

Instance creation defines new to return a copy of the prototype. 

Instance Protocol 

Accessing has one method which calls the class method pointersSize to answer the 
number of elements in pointers and another method which calls the class method 
to return the number of pointers. 

Adding Classes to this Hierarchy 

If you are adding a subclass of FixedSizeExternalPointerData and the conventions 
described in this manual under ExternalPointerData are unclear to you, the best 
idea is to find a structure class similar to the structure you are adding and model 
your class on the similar one. Your new class' protocol must include a class 
initialization method which initializes the class variables, sizelnBytes, and 
prototype. Remember to execute the initialize method for the new class. 

Related Classes 

Subclasses: 
lovec 
Msghdr 

You might also want to look at ExternalPointerData and ExternalData. 
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OS-Parameters 



ExternalBinaryData variableByteSubclass: #Inaddr 


instanceVariableNames: 


" 


classVariableNames: 


'AddrDatalndex BIDatalndex B2Datalndex 




B3Datalndex B4Datalndex W1 Datalndex 




W2Datalndex ' 


poolDictionaries: 


" 


category: 


'OS-Parameters' 



Summary 

inaddr provides accessing protocol for the following C structure. 



struct in_addr { 
union { 



} S_un; 
#define 

#d8fine 
#define 
#define 
#define 
#define 
} 



struct { u_char s_b1 , s_b2, s_b3, s_b4; } S_un_b; 
struct { u_short s_w1 , s_w2; } S_un_w; 
ujong S_addr; 



s_addr 

s_host 
s_net 
sjmp 
sjmpno 
s Ih 



S_un.S_addr 

S_un.S_un_b.s_b2 
S_un.S_un_b.s_b1 
S_un.S_un_w.s_w2 
S_un.S_un_b.s_b4 
S un.S un b.s b3 



/* can be used for most 

tcp and ip code ♦/ 

/* host on imp */ 

/* network */ 

/♦ imp ♦/ 

/* imp # */ 

/* logical host ♦/ 



The structure is referred to under inet(4N) in the manual UTek Command Reference, 
Volume 2. The structure is found in netinet/in.h. Protocol is provided to set the values 
from an integer and from a string. 

Class Variables 

AddrDatalndex 

BIDatalndex 

B2Datalndex 
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BSDatalndex 
B4Datalndex 
WIDatalndex 
W2Dataindex 



Each C structure class variable holds the offset of a single field in the 
structure. The name of a class variable is constructed from a field name, 
stripped of its prefix, with the string 'Datalndex' appended. For example, 
the class variable BSDatalndex holds the offset of the "s b3" field. 



Instance Methods 

accessing 
addr 



Return the value of the internet address as an integer. 

addr: aninteger 

Assign the argument, aninteger, as the internet address. 



converting 



asString 

Return the value of the internet address as a string. 



printing 



printOn: aStream 

Print the receiver in internet format on aStream. 



private 



fromStrIng: anInternetAddress 

Assign anInternetAddress string (in dot notation) to the receiver. 



Class Methods 



class initialization 

initialize 

Assign offset values to the class variables and define the size of the 
structure. 
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instance creation 

addr: an Integer 

Return an instance constructed from the internet address, aninteger. 

fromString: anInternetAddressString 

Return an instance constructed from the internet address, 
anInternetAddressString. 

Rationale 

This class is the C structure which holds an internet address. It holds a network 
address, and is used by the class Sockaddrln. The structure is used in support of 
the following UTek system calls: 

accept(2) 

bind(2) 

connect(2) 

getpeername(2) 

getsockname(2) 

recyfrom(2) 

sendto(2) 

Related Classes 

UTekSystemCall implements the system calls listed above. 
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ExternalBinaryData variableByteSubclass: #lntegerPointer 

instance VariableNames: 

class VariableNames: 

poolDictionaries: 

category: 'OS-Parameters' 



Summary 

IntegerPointer provides creation and accessing protocol for integer pointers. 
Integer pointers are defined in C with the type-specifier 'int *'. A four-byte buffer 
stores integer values. 



Instance Methods 

accessing 



Integer 

Return the signed integer that the receiver represents. 

integer: anint 

Assign the value, anint, to the receiver. 



printing 



printOn: aStream 

Print the receiver on aStream. 



Class Methods 



class initialization 

initialize 

Define the size of the structure. 

instance creation 

integer: anint 

Return an instance whose value is the machine integer for anint. 
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Rationale 

An argument to a system call that needs an integer pointer uses an instance of class 
IntegerPointer. An example use is in getpeername(2), where the size of the remote 
machine name returned is an instance of this class. 
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ExternalPointerData subclass: #lovec 

instanceVariableNames: 

classVariableNames: 'BaseDatalndex BasePointerlndex LenDatalndex 

poolDictionaries: 

category: 'OS-Parameters' 



Summary 

lovec provides creation and accessing protocol for the following C structure. 

struct iovec { 

caddr_t iov_base; 

int iovjen; 

} 

Each iovec entry specifies the base address and length of an area in memory. The 
structure is documented under read, readv(2) in the manual UTek Command Reference, 
Volume 2. 

Class Variables 

BaseDatalndex 

BasePointerlndex 

LenDatalndex 

Each C structure class variable holds the offset of a single field in the 
structure. The name of a class variable is constructed from a field name, 
stripped of its prefix, with the string 'Datalndex' appended. For example, 
the class variable BaseDatalndex holds the offset of the "iov_base" field. 

For fields with a pointer data type, a class variable is created for the index 
of that pointer in the structure; the name is constructed from the field name, 
stripped of its prefix, with the string 'Pointerlndex' appended. For example, 
the class variable BasePointerlndex holds the index "1 " because it is the 
first pointer in the iovec structure. 
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Instance Methods 

accessing 



base ' 

Return the value of the structure field named base. 

base: aString 

Assign the argument aString to the structure field named base, and assign 
aString's size to the structure field named len, 

len Return the value of the structure field named len. 



printing 



printOn: aStream 

Print the receiver on aStream. 



Class Methods 



class initialization 

initialize 

Assign offset values to the class variables, define the size of the structure, 
and initialize the prototype. 

instance creation 

base: aString 

Return an instance with the values of the fields assigned. 

Rationale 

The iovec C structure is used in support of the following UTek system calls: 

readv(2) 
writev(2) 

Related Classes 

UTelcSystemCall implements the system calls listed above. 
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ExternalBinaryData variableByteSubclass: #ltimerval 


instance VariableNames: 


" 


class VariableNames: 


'IntervalDatalndex IntervalSecDatalndex 




IntervalUsecDatalndex ValueDatalndex 




ValueSecDatalndex ValueUsecDatalndex ' 


poolDictionaries: 


" 


category: 


'OS-Parameters' 



Summary 

Itimerval provides creation and accessing protocol for the following C structure. 

struct itimerval { 

struct timeval itjnterval; /♦ timer interval ♦/ 

struct timeval it_value; /♦ current value ♦/ 
} 

The structure is documented under getitinier(2) in the manual UTek Command 
Reference, Volume 2. 

Class Variables 

IntervalDatalndex 

IntervalSecDatalndex 

IntervalUsecDatalndex 

ValueDatalndex 

ValueSecDatalndex 

ValueUsecDatalndex 

Each C structure class variable holds the offset of a single field in the 
structure. The name of a class variable is constructed from a field name, 
stripped of its prefix, with the string 'Datalndex' appended. For example, 
the class variable IntervalDatalndex holds the offset of the "itjnterval" 
field. 
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When a field in a structure is another C structure, separate class variables 
are created for each field in t[ie other structure. For example, the class 
variable IntervalSecDatalndex holds the offset of the "sec" field of the 
"it interval" structure. 



Instance Methods 

accessing 
interval 



Return the value of the structure field named interval. 

Interval: aTimeval 

Assign the argument, aTimeval, to the structure field named interval. 

interval: aTimeval value: anotherTimeval 

Assign values to all the fields of the structure. 

IntervalSec 

Return the sec field of the structure at the field named interval. 

intervalUsec 

Return the usee field of the structure at the field named interval. 

value 

Return the value of the structure field named value. 

value: aTimeval 

Assign the argument, aTimeval, to the structure field named value. 

valueSec 

Return the sec field of the structure at the field named value. 

valueUsec 

Return the usee field of the structure at the field named value. 



printing 



prIntOn: aStream 

Print the receiver on aStream. 
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Class Methods 



class initialization 

Initialize 

Assign offset values to the class variables and define the size of the 
structure. 

instance creation 

interval: aTlmeval vaiue: anotherTimeval 

Return an instance with the values of the fields assigned. 

Rationale 

The structure is used in support of the following UTek system calls: 

getitimer(2} 
setitimer(2) 

Related Classes 

UTel<SystemCaii implements the system calls listed above. 
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OS-Parameters 



ExternalBinatyData variableByteSubclass: #Ltchars 


instance VariableNames: 


" 


classVariableNames: 


'DsuspcDatalndex FlushcDatalndex 




LnextcDatalndex RprntcDatalndex 




SuspcDatalndex WerascDatalndex ' 


poolDictionaries: 


" 


category: 


'OS-Parameters' 



Summary 

Ltchars provides accessing protocol for the following C structure. 



struct ltchars { 




char t_suspc; 


/♦ stop process signal ♦/ 


char t_dsuspc; 


/♦ delayed stop process signal */ 


char t_rprntc; 


/* reprint line */ 


char t_flushc; 


/* flush output (toggles) */ 


char t werasc; 


/* word erase */ 


char tjnextc; 


/* literal next character ♦/ 



} 

The structure is documented under //yl'^j in the manual UTek Command Reference, 
Volume!. 

Class Variables 

DsuspcDatalndex 
FlushcDatalndex 
LnextcDatalndex 
RprntcDatalndex 
SuspcDatalndex 
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WerascDatalndex 



Each C structure class variable holds the offset of a single field in the 
structure. The name of a class variable is constructed from a field name, 
stripped of its prefix, with the string 'Dataindex' appended. For example, 
the class variable DsuspcDatalndex holds the offset of the "t_dsuspc" 
field. 



Instance Methods 

accessing 



dsuspc 

Return the value of the structure field named dsuspc. 

dsuspc: aCharacter 

Assign the argument, aCharacter, to the structure field named dsuspc. 

flushc 

Return the value of the structure field named flushc. 

flushc: aCharacter 

Assign the argument, aCharacter, to the structure field named flushc. 

Inextc 

Return the value of the structure field named Inextc. 

Inextc: aCharacter 

Assign the argument, aCharacter, to the structure field named Inextc. 

rprntc 

Return the value of the structure field named rprntc. 

rprntc: aCharacter 

Assign the argument, aCharacter, to the structure field named rprntc. 

suspc 

Return the value of the structure field named suspc. 

suspc: aCharacter 

Assign the argument, aCharacter, to the structure field named suspc. 

suspc: sCharacter dsuspc: dCharacter rprntc: rCharacter 
flushc: f Character werasc: wCharacter Inextc: ICharacter 
Assign values to all the fields of the structure. 
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werasc 

Return the value of the structure field named werasc. 

werasc: aCharacter 

Assign the argument, aCharacter, to the structure field named werasc. 



printing 



printOn: aStream 

Print the receiver on aStream. 



Class Methods 



class initialization 

initialize 

Assign offset values to the class variables and define the size of the 
structure. 

instance creation 

defauit 

Return an instance containing the default characters. 

Rationale 

The structure is used in support of the following UTek system call: 
ioctl(2) 

Related Classes 

UTekSystemCall implements the system call listed above. 
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OS- Parameters 



ExternalPointerData subclass" 


#Msghdr 


instance VariableNames: 


" 


classVariableNames: 


'AccrightsDatalndex AccrightslenDatalndex 




AccrightsPointerlndex lovDatalndex 




lovlenDatalndex lovPointerlndex NameDatalndex 




NamelenDatalndex NamePointerlndex ' 


poolDictionaries: 


" 


category: 


'OS-Parameters' 



Summary 

Msghdr provides creation and accessing protocol for the following C structure. 



/* optional address */ 
/* size of address */ 
/* scatter/gather array */ 
/* # elements in msgjov */ 
/* access rights sent/received */ 



struct msghdr { 




caddr t 


msg_name; 


int 


msg_namelen; 


struct iovec 


♦msgjov; 


int 


msgjovlen; 


caddr t 


msg_accrights; 


int 


msg_accrightslen; 



} 



The structure Is documented under recvmsg(2) in the manual UTek Command 
Reference, Volume 2. 

Class Variables 

AccrightsDatalndex 

AccrightslenDatalndex 

AccrightsPointerlndex 

lovDatalndex 

lovlenDatalndex 

lovPointerlndex 

NameDatalndex 
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NamelenDatalndex 
NamePointerlndex 



Each C structure class variable holds the offset of a single field in the 
structure. The name of a class variable is constructed from the field name, 
stripped of its prefix, with the string 'Datalndex' appended. For example, 
the class variable AccrightsDatalndex holds the offset of the 
"msg_accrights" field. 

For fields with a pointer data type, a class variable is created for the index 
of that pointer in the structure; the name is constructed from the field name, 
stripped of its prefix, with the string 'Pointerlndex' appended. For example, 
the class variable AccrightsPointerlndex holds the index "3" because it is 
the third pointer in the msghdr structure. 



Instance Methods 

accessing 



accrights 

Return the value of the structure field named accrights. 

accrights: aString 

Assign the argument, aString, to the structure field named accrights, and 
assign aString 's size to the structure field named accrightslen. 

accrightslen 

Return the value of the structure field named accrightslen. 

lov Return the value of the structure field named iov. . 

lev: anIovecArray 

Assign the argument, anIovecArray, to the structure field named iov, and 
assign anIovecArray 's size to the structure field named iovlen. 

iovlen 

Return the value of the structure field named iovlen. 

name 

Return the value of the structure field named name. 

name: aString 

Assign the argument, aString, to the structure field named name, and 
assign aString 's size to the structure field named namelen. 

name: aString lov: anIovecArray accrights: anotherString 
Assign values to all the fields of the structure. 
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namelen 

Return the value of the structure field named namelen. 



printing 



prIntOn: aStream 

Print the receiver on aStream. 



Class Methods 



class initialization 

initialize 

Assign offset values to the class variables, define the size of the structure, 
and initialize the prototype, 

instance creation 

name: aString iov: anIovecArray accrights: accString 

Return an instance with the values of the fields assigned. 

Rationale 

The msghdr C structure is used in support of the following UTek system calls: 

recvmsg(2) 
sendmsgil) 

Related Classes 

UTel<SystemCalI implements the system calls listed above. 
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PipeReadStream variableSubclass: #OSFilter 

instanceVariableNames: 'task stdin stderr ' 

classVariableNames: 

poolDictionaries: 

category: 'OS-Streams' 



Summary 

An OSFilter provides bi-directional communication with a utility program, which may 
be either an operating system utility or a user supplied program. It understands 
accessing protocol for both PipeReadStream and PipeWrlteStream. Writing to an 
OSFilter causes its task to receive standard input. Reading an OSFilter causes the 
task to supply its standard output. The utility is not required to read standard input 
(in which case writing protocol has no effect), nor to write standard output or 
standard error (in which case reading protocol never shows data available). Note 
that the utility may not produce output immediately, depending on how it buffers its 
output. 

Instance Variables 

stderr <PipeReadStream> 

The stream that collects the utility's standard error output. 

stdin <PipeWriteStream> 

The stream that supplies the utility with standard input. 

task <Subtask> 

The system utility being used as a filter. 



Instance Methods 

initialize-release 



InitiaiizeErrorOn: aPipe 

Initialize the error output side of the filter stream with the supplied pipe 
which contains an open read file descriptor. 

initlalizeErrorOnFd: fd 

initialize the error output of the filter stream with the supplied file descriptor, 
which Is assumed to be the reading end of a Pipe. 



Tektronix Smalltalk Reference Manual 101 



OS Filter OS-Streams 



initializelnputOn: aPipe 

Initialize the input side of the filter stream with the supplied pipe which 
contains an open write file descriptor. 

InltlalizelnputOnFd: fd 

Initialize the input side of the filter stream with the supplied file descriptor, 
which is assumed to be the writing end of a Pipe. 

accessing 

InputBinary 

Set the mode of this OSFilter to binary. 

InputText 

Set the mode of this OSFilter to text. 

nextError 

Answer a String containing the next line from the error stream. 

nextPut: aCharacter 

Place aCharacter in the task's input stream. 

nextPutAII: aCollection 

Place all the data in aCollection in the task's input stream. 

outputBlnary 

Set the OSFilter's output to be buffered in binary mode. 

outputText 

Set the OSFilter's output to be buffered in text mode. 

opening-closing 

abort 

Clean up. Close all PipeStreams and terminate the task. 

close 

Close the standard input to the task. Return whatever might be produced 
in standard output. Close standard output and standard error and 
terminate the task. 

closeError 

Close the error output from the task. Return whatever might have been 
there. 

closelnput 

Close the standard input to the task. Normally this causes the task to 
terminate. 
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openOn: aCommand withArguments: aColIection 

Initialize the filter by opening input and output streams and starting the 
task. 

positioning 

flush 

Chase something through the filter with multiple line terminators. 

flushWith: aCharacter blockSIze: count 

Chase something through the filter with count occurrences of the given 
character. 

printing 

prIntOn: aStream 

Place in aStream a String that describes the program and arguments of an 
OSFilter. If the task is inactive, so state. 

testing 

IsActive 

Is this filter's task active? 

Class Methods 

examples 

example 

Use sed and cpp to extract key-value pairs from the header file, 
'errno.h'. 

valuesFromHeader: aHeaderFlIe 

Use sed and cpp to extract a Dictionary of key-value pairs from a header 
file. This may take a few minutes. 

instance creation 

openOn: aCommand 

Create a new OSFilter, with its input and output streams directed to/from 
aCommand. 

openOn: aCommand withArguments: aCollection 

Create a new OSFilter, with its input and output streams directed to/from 
aCommand, Pass aCollection of arguments to aCommand upon 
execution. 
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Rationale 

OSFIIter was designed as a general purpose tool for programmers to be able to use 
operating system utilities or user supplied programs from within Smalltalk. 

Background 

Filters 

Filters are programs which process a character stream — usually, they modify the 
stream. There are some filters, such as cat, which do not modify their input, but they 
are not used as examples here. The filter has an input side and an output side — in 
UTek the reading is usually done from standard input. 

In building the operating system interface to Tektronix Smalltalk, it quickly became 
apparent that many of the utility programs available could find use within Smalltalk. 
Without OSFIIter, Smalltalk could receive output from an operating system program 
using the UTekSystemCall method executeUtllity:wlthArguments:, but it couldn't 
provide input to the operating system program. The background menu item "OS 
Shell" would allow user interaction with various programs, but there was no simple 
means for a Smalltalk method to interact with a program. 

Two-Way Communication 

What was needed was a facility for bi-directional communication with a utility 
program. OSFIIter accomplishes this by running a utility program with individual 
PipeStreams for the program's standard input and standard output. OSFIIter is 
designed for portability across operating systems. 

Examples 

The following example illustrates the use of an instance of OSFIIter to access the 
UTek program wc. This code can be executed in a workspace. 

wc «- OSFilter openOn: '/bin/wc'. "path for UTek only" 

wc nextPutAll: 'How many lines, words and characters are there 

in this string?'. 

wc closelnpuL 

lines 4- wc nextCNumber. 

words 4- wc nextCNumber. 

characters <- wc nextCNumber. 

wc close. 

Transcript cr; show: lines printString, ' lines, ', 

words printString, ' words, and ', 

characters printString, ' characters are in the string.' 
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When the preceding code is executed in a workspace, this output appears in the 
System Transcript: 

2 lines, 1 1 words, and 62 characters are in the string. 

An Example from the Image 

A more complex example of an OSFilter application is found in the OSFilter class 
method valuesFromHeader: under the examples protocol. 

valuesPromHeaden aHcaderPilc 

"Use sed and cpp to extract a Dictionary of key-value pairs from a C 

header file. This may take a few minutes." 
"(OSFilter valuesFromHeader: 'lusrHncludelsyslmax.h') inspect." 

I sed cpp key symbolTable | 

symbolTable <- Dictionary new: 128. 

"Open a sed filter that will extract just C preprocessor symbols from a 

given file." 
sed <- OSFilter openOn: 7bin/sed' withArguments: (OrderedCoUection 
with: '-n' 

"A space and a tab are inside the square brackets below that appear empty. 
with: 

's/#[ ]*define[ ][ ]*\([A-Za-zJ[0-9A-Za-zJ*\)[ ].*Al/p' 
with: aHeaderFile). 
sed closelnpuL 
"Open a C preprocessor filter, feed it the given file, and discard whatever 

that might produce." 
cpp <- OSFilter openOn: 71ib/q)p'. 
cpp nextPutAU: '#include '", aHeaderFile, "". 
cpp flush; nextAvailable. "Discard uninteresting output." 

"Feed each symbol from sed into cpp, collect its output in a Dictionary." 
[sed atEnd] 
whileFalse: 

[key <— sed nextLine. 
key ~= " ifTrue: 

[cpp nextPutAll: key. 

cpp flush. 

symbolTable at: (key copyUpTo: Character cr) asSymbol 

put: cpp nextCNumber. 
cpp nextAvailable]]. "Discard the flush characters." 

sed close. 
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cpp close. 
TsymbolTable 

Here is a description of what the code is doing. The method valuesFromHeader: 
takes a ".h" file (a C header file) and finds all the non-argument defines in the form 

#define identifier token-string 

and creates dictionary entries with the defined identifier and its associated token- 
string, a CNumber, This method only creates dictionary entries for defined identifiers 
whose associated token-string is a valid C number, using the PositionableStream 
method nextCNumber. 

The sed filter only extracts simple identifiers, not parameterized ones (with 
arguments). For example, 

#define sqr(x) (x * x), 

will not cause sqr to be entered in the dictionary. 

First the dictionary called symboWable is created. Then a sed OSFilter is run on the 
header file with the operating system sed command that causes only the defined 
identifiers to appear in the output stream, one per line. Input to sed is closed, 
causing all of the data from sed to become available. A cpp OSFilter is opened and 
given the header file as input. Cpp Is flushed and a loop begins in which sed output 
is sent to cpp, one line at a time, and the identifier from sed is placed into the 
dictionary symbolTable with its associated CNumber from cpp. After each line from 
sed goes into key and then to cpp, cpp is flushed. Cpp buffers its output and we want 
it to deal with one identifier at a time. (Flush outputs multiple line terminators, so 
they must be discarded by sending cpp the message nextAvaiiable.) When the 
data from sed are exhausted the loop terminates, both filters are closed, and 
symbolTable is returned. 

Related Classes 

An instance of Subtask is the program, residing in the operating system, that is 
serving as the filter in the OSFilter. In addition to reading about Subtask, it will also 
be useful to look at the Stream hierarchy, in particular, OSFIIter's superclass, 
PipeReadStream. 
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Object subclass: #Pipe 

instance VariableNames: 
class VanableNames: 
poolDlctionaries: 
category: 


'readFd writeFd fileDescriptor ' 
'OS-Interface' 



Summary 

An Instance of Pipe represents an operating system pipe in Smalltalk. Operating 
system pipes are unidirectional communication links, usually between Smalltalk and 
a child task in our context. A pipe has two file descriptors, one for each end of the 
pipe. One end of the pipe is for reading, the other for writing. A system buffer holds 
the contents of the pipe. 

Communication between tasks is accomplished via a PIpeStream which is opened 
using one of the two descriptors, depending on the direction. Two way 
communication between two tasks requires two pipes. 

Instance Variables 

fileDescriptor <lnteger> 

The read or write file descriptor used to access the parent's end of the 
pipe. 

readFd <lnteger> 

The file descriptor used to access the reading end of the pipe. 

writeFd <lnteger> 

The file descriptor used to access the writing end of the pipe. 



Instance Methods 

initialiie-release 



readFd: readingEnd writeFd: writingEnd 

Initialize a new Pipe with the given reading and writing file descriptors. 

release 

Close both ends of the pipe. 
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accessing 



fileDsscrlptor 

Return the file descriptor to be used for streaming over data, eitlner the 
readFd or the writeFd. 

readFd 

Return the file descriptor representing the read end of the pipe. 

writeFd 

Return the file descriptor representing the write end of the pipe. 

copying 

copy 

Inappropriate for a Pipe. 

opening-closing 

closeRead 

Close the read side of the pipe. 

closeWrite 

Close the write side of the pipe. 

fileDescriptor: fd 

Fd, which is either this Pipe's readFd or its writeFd, becomes the 
descriptor to be accessed for streaming over data. 

mapReadTo: fd 

Map the read side of the pipe to the specified descriptor fd, 

mapWriteTo: fd 

Map the write side of the receiver's pipe to the specified descriptor fd. 



Class Methods 

instance creation 
new 



Return an instance of Pipe. 

readFd: readingEnd writeFd: writingEnd 

Create a new Pipe, with the given reading and writing file descriptors. 
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Rationale 

An instance of Pipe is a temporary lioiding place for file descriptors. Once a Pipe's 
file descriptor is passed to a PipeStream, the Pipe is no longer needed, and should 
not be referenced. 



Discussion 

instances of Pipe are created using either of two instance creation messages. The 
message new causes the operating system to return the pipe's file descriptors. The 
message readFdrwriteFd: creates a new Pipe using file descriptors obtained by 
some other means (e.g., OS duplicateFd:). 

To insure portability, instead of sending the message new to the class Pipe, 
instances should be created this way: 

OS newPipe. 

The initialize-release message reiease closes the reading and writing ends of the 
pipe. Closing pipes is often accomplished using the separate opening-closing 
messages closeRead and closeWrite. 

Accessing messages return the values of a Pipe's three instance variables. 

Protocol exists for mapping ends of the pipe to arbitrary file descriptors. The 
methods mapReadTo: and mapWriteTo: make operating system calls to duplicate 
the argument, a file descriptor. Mapping allows communication between parent and 
child tasks. 

Examples 

The OSFiiter method openOn:withArguments: contains several examples of 
typical pipe usage: 

openOn: aCommand withArguments: aCoUection 

"Initialize the filter by opening input and output streams and 
starting the task." 

I in out err j 
in <— OS newPipe. 
out «- OS newPipe. 
err <- OS newPipe. 
self initializeOn: out 
self initializelnputOn: in. 
self initializeErrorOn: err. 
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self task: (Subtask 

fork: aCommand 
withArguments: aCollection 
standardin: in 
standardOut: out 
standardError. err), 
self task start isNil 
ifTrue: 

[self stdin close, 
self close. 

Transcript show: self closeError. 
self error: 'Cannot execute ' , aCommand]. 
in closeRead. 
out closeWrite. 
err closeWrite 

The three temporary variables in, out, and err each receive new Instances of Pipe 
via the message newPipe. Newpipe is always sent to the current operating system 
call class (referred to by the global variable OS). The following initialization 
messages cause the OSFIIter to get the proper file descriptors of the three Pipes — 
the OSFilter doesn't get the Pipes themselves. In the Subtask creation message, 
the new Subtask gets the file descriptors for the opposite ends of the three Pipes. 
Finally, the ends of the Pipes not needed by the OSFIIter (i.e., those given to the 
Subtask) are closed. When this method completes, the three Pipes are no longer 
referenced and are garbage collected. 

The method above is a succinct example of a portable system call, subtasking, and 
the use of pipes in the class OSFilter. 



Related Classes 

These classes are related to Pipe: 

OSFilter 

PipeStream 

PIpeReadStream 

PIpeWriteStream 

Subtask 
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PipeStream subclass: #PipeReadStream 

instanceVariableNames: 'foundEnd ' 

classVariableNames: 

poolDictionaries: 

category: 'OS-Streams 



Summary 

PipeReadStreams are used for reading from an operating system pipe. Data are 
buffered from the pipe to avoid excessive reads. Protocol for reading all the data 
available from the pipe is provided by using the size of the pipe as an indicator of 
how much to read — reading more data than are available can result in blocking. 

Instance Variables 

foundEnd <Boolean> 

True if the end of the pipe has been encountered. 



Instance Methods 

initialize-release 



initializeOn: aPipe 

Initialize this PipeStream with aPipe, which must contain an open read file 
descriptor. 

initializeOnFd: fd 

Initialize this PipeStream with the supplied open file descriptor, which must 
refer to a Pipe. 



accessing 



binary 

Set the receiver's file to be buffered in binary mode. Copy any already 
buffered data to the new buffer, a ByteArray. 

contentsOfEntlreFile 

Read all of the contents of the receiver. If the PipeReadStream buffer 
contains something, prepend it to the results. 
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next 

Return the next character or byte from the PipeReadStream. Answer nil if 
at the end of the stream. 

next: aninteger 

Return the next aninteger bytes from the PipeReadStream. Return a 
ByteArray if the stream is binary, return a String if the stream is text. 

next: aninteger into: aCollection 

Copy the next aninteger bytes from the receiver into aCollection. Answer 
aCollection. 

nextAvailable 

Answer a collection containing all available data from the pipe. Answer an 
empty collection if no data are available. Answer nil if something is wrong 
with the pipe. 

nextPut: anObject 

Not apropriate for a PipeReadStream. 

text 

Set the receiver's file to be buffered in text mode. Copy any already 
buffered data to the new buffer, a String. 

e?mmerating 

doAvailable: aBlock 

Evaluate aBlock for each object in the pipe. 

doByLine: aBlock 

Evaluate aBlock for each string ending with a line terminator in the pipe. 
Do not include the line terminator in the string. 

positioning 

skip: count 

Discard the next count items in the stream. 

testing 

atEnd 

Return true if the end was previously found or answer a guess based on 
the size of the contents of the pipe. 

dataAvailable 

Return true if there are any data ready to be read from the pipe. 
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is Empty 

Return true if the pipe contains no data. 

Rationale 

This class allows the reading of data from an operating system pipe. Using a 
PipeReadStream, a Smalltalk process can obtain data from a related process. 

Discussion 

The abstraction of a pipe stream is used outside of Smalltalk, for example, several C 
functions use a stream for reading, including fscanf, gets, and getc. Most users are 
familiar with the standard input stream, stdin. 

Streams make accessing data easier, because they "know" the position where 
reading or writing can occur. It isn't necessary for you to keep track of how many 
characters have been read so that you can specify which character to read next. A 
stream knows when it has reached the end of its data and when it is empty. 

Protocol 

To create an instance of PipeReadStream, you should use an instance creation 
message inherited from the superclass, PipeStream — for example, send the 
message openOn: to PipeReadStream. 

Initialize-release methods initialize appropriate instance variables and add this 
PipeReadStream to the class variable OpenPipeStreams. 

Accessing methods set the mode instance variable and, if the mode was incorrect, 
copy the data into the correct type of buffer (ByteArray or String). Data in the 
stream can be read — the entire file, only the contents of the buffer, a single byte, 
or a specified number of bytes. Data from the stream can be read and returned in a 
Coliection. The inherited message nextPut: is intercepted because this is a 
stream for reading. 

Enumerating methods evaluate a block for each byte/character or each line in the 
stream. 

Positioning allows you to skip over (discard) a specified number of bytes/characters 
in the stream. 

Testing methods answer whether the end of the stream's data has been reached, 
whether there are data available for reading, and whether the pipe is empty. 
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Examples 

The following method is found under SystemDictionary initialize-release. 

startup 

"Do all that is necessary to begin execution of a Smalltalk image." 

I stdin I 

ScheduledControllers restore. 
OS notNil ifTrue: 

[(OS status: 0) fileSize = 
ifFalse: 

[stdin <- PipeReadStream openOnFd: (OS duplicateFd: with: 5). 
Transcript refresh; cr; cr; show: 'Filing in from: standard input'; cr. 
stdin fileln; close]. 
Sub task markAndSignalAli; install]. 
Sensor cursorPoint: Display viewport topLeft 

In addition to starting Smalltalk, the method above provides the ability for you to 
pass a file or "dolt" to Smalltalk from the command line when you invoke an image. 
It makes a system call to determine if the pipe for standard input (file descriptor = 0) 
has size 0. If there is anything in that pipe, an instance of PipeReadStream is 
created on standard input, but using a different file descriptor — the duplicateFd: 
message links the new stream with standard input. Next the "filing in" message is 
displayed in the System Transcript. Smalltalk then attempts to "file in" whatever is 
present in standard input. If the standard input is not in "file in" format, a syntax 
error will result. Typical fileln files have names ending in .st or .ws. Here are two 
examples of command lines which pass arguments to Smalltalk: 

echo "Transcript show: 'Your message here.'.!" j <smalltalk or imageNamo 

cd <smalltalk fileln directory> 
Smalltalk < Clock.st 

In the first example you would type Smalltalk or the name of your image in the 
position indicated by the angle brackets (< >). The string you type as the argument 
to show: will be displayed in the System Transcript when the image comes up. In 
the second example, you first cd to the directory which contains the fileln files. 
Without moving to that directory, you could accomplish the same thing by giving the 
full path of Clockst on line two. The clock code will be filed in when the image 
comes up. The first example uses a shell pipe operator ( | ); the second example 
uses a shell I/O redirection operator ("<" for input). 
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Related Classes 

Subclasses: 
OSFIIter 

You will find it helpful to look at the following classes for a further understanding of 
this class: 

• the PlpeStream hierarchy, 

• Pipe, and 

• methods nextLine and nextCNumber in PositionableStream. 
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ExternalStream subclass: #PipeStream 

instanceVariableNames: 'fileDescriptor mode ' 

classVariableNames: 'OpenPipeStreams ' 

poolDictionaries: 

category: 'OS-Streams' 



Summary 

PipeStreams are stream-based interfaces to operating system pipes. PipeStream 
is an abstract class Implementing protocol common to PIpeReadStream and 
PipeWriteStream, such as opening, closing, and accessing methods. 

Instance Variables 

fileDescriptor <lnteger> 

The file descriptor by which the underlying pipe is accessed. 

mode <Symbol> 

Either #binary or #text, depending on what type of data is expected to be 
used on the underlying pipe. 

Class Variables 

OpenPipeStreams <OrderedCollection> 

All open PipeStreams are listed here. 



Instance Methods 

initialize-release 



InitializeOnFd: anFd 

Initialize the pipe stream with the supplied open file descriptor, which must 
refer to a Pipe. 



accessing 



binary 

Set the mode of this PipeStream to binary. 

bufferClass 

Return the class that is used as a buffer for this PipeStream, depending on 
the data type which has been selected. 
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contents 

Not appropriate for a PipeStream. 

fileDescriptor 

Answer the descriptor to be accessed for streaming over data. 

fileDescriptor: fd 

Store tiie argument as the descriptor to be accessed for streaming over 
data. 

size 

Return the size of the PipeStream contents as reported by the operating 
system. 

text 

Set the mode of this PipeStream to text. 

copying 

copy 

Not appropriate for a PipeStream. 

opening-closing 

close 

Disassociate this PipeStream with its underlying pipe. Make sure that the 



pipe exists, then make sure it is closed. 



positioning 



padTo: an Integer 

Not appropriate for a PipeStream. 

padTo: bsize put: aCharacter 

Not appropriate for a PipeStream. 

position: aninteger 

Not appropriate for a PipeStream. 

reset 

Not appropriate for a PipeStream. 

resetContents 

Not appropriate for a PipeStream. 

setToEnd 

Not appropriate for a PipeStream. 
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skip: aninteger 

Not appropriate for a PipeStream. 

wordPosltlon: wp 

Not appropriate for a PipeStream. 

testing 

atEnd 

Is this PipeStream at the end of its data? 

IsBlnary 

Does this PipeStream contain binary data? 

IsText 

Does this PipeStream contain textual data? 

isValid 

Does this PipeStream reference an open pipe? 

Class Methods 

class initialization 

initialize 

Initialize the class variable used for tracking open PipeStreams. 

external references 

numberOfExternalReferences 

Return the number of references to open PipeStreams. 

release ExternalReferences 

Close all the open PipeStreams known to Smalltalk. 

instance creation 

openOn: aPipe 

Create a new PipeStream, streaming over aPipe. 

openOnFd: fd 

Create a new PipeStream, streaming over a Pipe, which is known by the 
open file descriptor fd. 

Rationale 

PipeStream is an abstract class whose subclasses are the primary means of 
communication with child tasks. Operating system pipes are usually implemented in 
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Smalltalk using PipeStream. An Important function of this class is to Intercept 
Inherited methods which are inappropriate for a PipeStream. Pipes are not 
posltionable, so PipeStream removes much oHhe positioning protocol from the 
Inheritance chain via "self shouldNotlmplement". 

Background 

Terminology 

Here is a clarification of some of the terms used in the description of the classes in 
the Stream hierarchy, and in particular, the PipeStream and FileStream 
hierarchies. 

File has a variety of meanings, depending upon your operating system. In the 
context of these classes, a file is a collection of data in external storage, referred to 
by a name. In this respect, files differ from operating system pipes, which are not 
named by the user. In Unix-like operating systems, the distinction between files and 
directories (and other non-file objects, as well) is blurred. The Implementations of 
FileStream and FlleDlrectory maintain that ambiguity, to some extent. See those 
classes for additional information. 

Pipes share a similarity with files in that both are holding places for data. The 
primary differences between the two are that pipes are transient (they do not reside 
in mass storage), they cannot be reopened once they are closed, and they are not 
posltionable. Like files, the operating system identifies pipes by a file descriptor. 
Pipes are conduits through which data "flow" in one direction. For two-way 
communication between two tasks, two pipes are needed. 

Streams are an abstraction for accessing data. Two types of streams are character 
streams and binary (integer) streams. Smalltalk has classes which represent 
internal streams and external streams. Stream classes assume that they are 
accessing an indexable Collection, such as a String. The external streams serve 
as interfaces to data in the operating system. ExternalStream establishes protocol 
for accessing nonhomogeneous collections of data. 

Discussion 

There is a fixed number of open file descriptors allowed by the operating system. 
To avoid running out of file descriptors, pipes should always be closed when they 
are no longer needed. The class variable OpenPlpeStreams manages the file 
descriptors held by PipeStreams. All open PipeStreams can be closed with the 
message releaseExternalReferences. 
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Snapshots 

If you make a snapshot and continue execution, any open PipeStreams will still be 
open. Reloading a snapshot causes all the PipeStreams in the class variable 
OpenPlpeStreams to be closed. Any subtasks that were running when a snapshot 
was made will no longer be running when the snapshot image is reloaded. In fact, 
any communication between an application and the operating system via a 
PipeStream will be terminated when a saved image is reloaded. The operating 
system closes file descriptors and terminates child tasks when the Smalltalk task 
terminates. 

Class Protocol 

Class initialization creates a new collection to record OpenPlpeStreams. 

External References answers the count of open PipeStreams and provides a 
message to close all PipeStreams. 

There are two instance creation methods — one takes an instance of Pipe as an 
argument, the other takes as an argument a file descriptor which is assumed to refer 
to an operating system pipe. 

Instance Protocol 

The initialize-release method is called by the instance creation methods. It sets two 
instance variables and adds the new PipeStream to the class variable 
OpenPlpeStreams. 

Methods under accessing set the instance variable mode to either #binary or #text; 
set or return the instance variable fiieDescriptor; return the class, String or 
ByteArray, used as the buffer for this PipeStream; and return the size of the buffer. 
The message contents, inherited from ReadWriteStream, is intercepted with "self 
shouldNotlmplement" in PipeStream — PIpeReadStream provides the method 
contentsOf EntireFile, which is appropriate for that class. 

Copying and positioning methods are intercepted. 

The message close disassociates the PipeStream from the operating system pipe 
and removes it from the OpenPlpeStreams collection. Note that the PipeStream 
may still be referenced by other objects, but typical accessing protocol for it will fail. 

Testing protocol answers whether the mode is binary or text, whether fiieDescriptor 
references an open operating system pipe, and whether the PipeStream is at the 
end of its data. 
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Related Classes 

Subclasses: 

PipeReadStream 
PIpeWrlteStrGam 

You may also want to look at Pipe. 
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PipeStream subclass: #PipeWriteStream 

instance VariableNames: 

classVanableNames: 

poolDictionaries: 

category: 'OS-Streams' 



Summary 

PipeWriteStreams are used for writing to an operating system pipe. Data are not 
buffered to the pipe. 



Instance Methods 

initialize-release 

initializeOn: aPipe 

Initialize this PipeStream with aPipe, which must contain an open write file 
descriptor. 

accessing 

next 

Not appropriate for a PipeWriteStream. 

next: aninteger 

Not appropriate for a PipeWriteStream. 

next: aninteger into: aCollection 

Not appropriate for a PipeWriteStream. 

nextPut: aCharacterOrByte 

Place aCharacterOrByte into the pipe. Do not buffer the data. Answer the 
data written. 

nextPutAII: aCollection 

Write the contents of the collection to the pipe. Don't buffer data into the 
pipe. 

peek 

Not appropriate for a PipeWriteStream. 
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peekFor: anObject 

Not appropriate for a PipeWriteStream. 

Rationale 

PipeWriteStream allows data to be passed to another operating system task. 

Discussion 

Tlie abstraction of a pipe stream is used outside of Smalltalk, for example, several C 
functions use a stream for writing, including fprintf and putc. Most users are familiar 
with the standard output stream, stdout. 

Instance creation messages from the superclass should be sent to PipeWriteStream 
to create an instance. Most of the inherited class protocol is not very practical for 
this class. 

The initialize-release method initializes appropriate instance variables and adds this 
PipeWriteStream to the class variable OpenPipeStreams. 

Accessing methods intercept inappropriate inherited messages and implement 
nextPut: and nextPutAII: to write a single byte/character or a collection to the 
stream. 

Examples 

The following code can be executed in a workspace. 

stderr <— PipeWriteStream openOnFd: 2. 

stderr nextPutAll: This gets printed on the screen.' 

The example opens a PipeWriteStream on the file descriptor (2) associated with 
standard error output, then writes a message on the standard error stream. This 
might be useful for debug messages while modifying the Transcript. 

Related Classes 

• OSFIIter uses this class. 

• The PIpeStream hierarchy contains protocol available to PIpeWrlteStreams. 

• Pipe may also be of interest to you. 
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ExternalPointerData subclass" 

instance VariableNames: 
classVariableNames: 
poolDictionaries: 
category: 


#PointerArray 

'OS-Parameters' 



Summary 

Instances of PointerArray represent an array of integers or pointers to objects. 
Elements of the array may be instances of concrete subclasses of ExternalData (or 
other variableByte or variableWord classes with no instance variables) or Integer. 
Every ExternalData object is given a pointer to it by the interpreter when certain 
primitives are invoked, integers (Smalllntegers or Largelntegers up to four bytes 
long) are given the value of the integer in question, not a pointer to the integer. 
Since Integers are thus treated differently than other objects, the ExternalData 
concrete subclass IntegerPointer is used to create a pointer to an integer. 

Protocol exists for instance creation, accessing array elements, initializing the 
inherited pointers instance variable, and printing the array. 



Instance Methods 

initialize- release 

initialize 

Store the proper offsets into the pointers array. 

accessing 

at: anindex 

Return the object at anindex in the pointers area. 

at: anindex put: anObject 

Place anObject at anindex in the pointers area. 



printing 



prIntOn: outStream 

Print a representation of the objects on the receiver. 
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Class Methods 

instance creation 

new 

Return an empty instance. 

new: count 

Create an instance with enough space for count data objects. 

Rationale 

PointerArray is used by the system call class for your operating system to pass 
arguments to system calls. 

Discussion 

In the current release (TB2.2.1), Pointer Arrays are only used for arrays of pointers 
to strings. The pointers instance variable of a PointerArray has a null-terminated 
String as the object half of each object-offset pair. The interpreter uses pointers to 
fill in the addresses in the space reserved for them in dataArea. 

Examples 

The following code spawns a child task to run the UTek Is utility with two arguments, 
-I and /usr/lib/smalltalk. You could execute the code in a workspace with "printit" to 
see the long listing of the contents of the directory /usr/lib/smalltalk. 

OS executeUtility: 7bin/ls' withArguments: (OrderedCollection 
with: '-r with: '/usr/lib/smaUtalkO. 

From the shell, the command line would be is -l /usr/lib/smalltalk. The 
example accomplishes its work by making an execve(2) system call. The execve(2) 
system call is one that expects an array of pointers to strings (actually, pointers to 
chars) as an argument. The following code (extracted from non-portable code found 
in the UTekSystemCall execute :wlthArguments:withEnvironment: method) 
constructs the PointerArray needed by the spawned task given in the example 
above. ArgCollection is an OrderedCollection specified in 
executeUtilityiwithArguments:. ArgCollection has two elements: '-I' and 
7usr/lib/smalltalk'. 

args <r- PointerArray new: argCoUection size + 1. "nil at end' 

i<-l. 

argCollection do: 

[:arg| args at: i put: arg, StringTerminator. 
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i<-i + 1]. 

An instance of PointerArray is created, one element larger than thie number of 
arguments — the extra element (nil) is required by the operating system to mark the 
end of the array. The temporary variable, /, is the index into the PointerArray. The 
PointerArray is filled by copying the elements from argCollection with a 
StrlngTermlnator appended to each element. 

Related Classes 

UTekSystemCall uses this class. 
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ExternalBinaryData variableByteSubclass: #RIimit 

instanceVariableNames: 

classVariableNames: 'CurDatalndex MaxDatalndex 

poolDictionaries: 

category: 'OS -Parameters' 



Summary 

Rlimit provides creation and accessing protocol for the following C structure. 

struct rlimit { 

long rlim_cur; /* current (soft) limit */ 

long rlim_max; /* maximum value for rlim_cur */ 

} 

The structure is documented under getrlimit(2) in the manual UTek Command 
Reference, Volume 2. 

Class Variables 

CurDatalndex 
MaxDatalndex 

Each C structure class variable holds the offset of a single field in the 
structure. The name of a class variable is constructed from a field name, 
stripped of its prefix, with the string 'Datalndex' appended. For example, 
the class variable CurDatalndex holds the offset of the "rlim cur" field. 



Instance Methods 

accessing 



cur Return the value of the structure field named cur. 

cur: anint 

Assign the argument, anint, to the structure field named cur. 
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cur: anint max: anotherint 

Assign values to all the fields of the structure. 

max 

Return the value of the structure field named max. 

max: anInt 

Assign the argument, anint, to the structure field named max. 



printing 



printOn: aStream 

Print the receiver on aStream. 



Class Methods 



class initialization 

initialize 

Assign offset values to the class variables and define the size of the 
structure. 

instance creation 

cur: anint max: anotherint 

Return an instance with the values of the fields assigned. 

Rationale 

The structure is used in support of the following UTek system calls: 

getrlimit(2) 
setrlimit(2) 

Related Classes 

UTekSystemCall implements the system calls listed above. 
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ExternalBinaryData variableByteSubclass: #Rusage 


instanceVariableNames: 


" 


classVariableNames: 


'IdrssDatalndex InblockDatalndex IsrssDatalndex 




IxrssDatalndex MajfltDatalndex MaxrssDatalndex 




MinfltDatalndex MsgrcvDatalndex 




MsgsndDatalndex NivcswDatalndex 




NsignalsDatalndex NswapDatalndex 




NvcswDatalndex OublockDatalndex 




StimeSecDatalndex StimeUsecDatalndex 




UtimeSecDatalndex UtimeUsecDatalndex ' 


poolDictionaries: 


" 


category: 


'OS-Parameters' 



Summary 




Rusage provides creation and accessing 


struct rusage { 




struct timeval 


ru_utime; 


struct timeval 


ru_stime; 


long 


ru_maxrss; 


long 


rujxrss; 


long 


rujdrss; 


long 


rujsrss; 


long 


ru_minflt; 


long 


ru_majflt; 


long 


ru_nswap; 


long 


rujnblock; 


long 


ru_oublock; 


long 


ru_msgsnd; 


long 


ru_msgrcv; 


long 


ru_nsignals; 


long 


ru_nvcsw; 


long 


ru_nivcsw; 



} 



protocol for the following C structure. 

/* user time used ♦/ 
/♦ system time used */ 

/* integral shared memory size */ 

/♦ integral unshared data size */ 

/* integral unshared stack size ♦/ 

/* page reclaims */ 

/* page faults ♦/ 

/* swaps */ 

/* block input operations ♦/ 

/* block output operations */ 

/* messages sent ♦/ 

/♦ messages received ♦/ 

/* signals received */ 

/* voluntary context switches */ 

/* involuntary context switches */ 



The structure is documented under getrusage(2) in the manual UTek Command 
Reference, Volume 2. 
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Class Variables 

IdrssDatalndex 

InblockDatalndex 

IsrssDatalndex 

IxrssDatalndex 

MajfltDatalndex 

MaxrssDatalndex 

MinfltDatalndex 

MsgrcvDatalndex 

MsgsndDatalndex 

NivcswDatalndex 

NsignalsDatalndex 

NswapDatalndex 

NvcswDatalndex 

OublockDatalndex 

StimeSecDatalndex 

StimeUsecDatalndex 

UtimeSecDatalndex 

UtimeUsecDatalndex 



Each C structure class variable holds the offset of a single field in the 
structure. The name of a class variable is constructed from a field name, 
stripped of its prefix, with the string 'Datalndex' appended. For example, 
the class variable IdrssDatalndex holds the offset of the "rujdrss" field. 

When a field in a structure is another C structure, separate class variables 
are created for each field in the other structure. For example, the class 
variable UtimeSecDatalndex holds the offset of the "sec" field of the 
"ru_utime" structure, timeval. 
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Instance Methods 

accessing 
idrss 



Return the value of the structure field named idrss. 

inblock 

Return the value of the structure field named inblock. 

isrss 

Return the value of the structure field named isrss. 

Ixrss 

Return the value of the structure field named ixrss. 

majfit 

Return the value of the structure field named majfit. 

maxrss 

Return the value of the structure field named maxrss. 

minfit 

Return the value of the structure field named minfit. 

msgrcv 

Return the value of the structure field named msgrcv. 

msgsnd 

Return the value of the structure field named msgsnd. 

nivcsw 

Return the value of the structure field named nivcsw. 

nsignals 

Return the value of the structure field named nsignals. 

nswap 

Return the value of the structure field named nswap. 

nvcsw 

Return the value of the structure field named nvcsw. 

oublock 

Return the value of the structure field named oublock. 

stime 

Return the value of the structure field named stime. 
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stImeSec 

Return the sec field of the structure at the field named stime. 

stImeUsec 

Return the usee field of the structure at the field named stime. 

utime 

Return the value of the structure field named utime. 

utimeSec 

Return the sec field of the structure at the field named utime. 

utimeUsec 

Return the usee field of the structure at the field named utime. 



printing 



printOn: aStream 

Print the receiver on aStream. 



Class Methods 



class initialization 

initialize 

Assign offset values to the class variables and define the size of the 
structure. 

instance creation 

callingProcess 

Return the rusage structure for the calling process. 

terminatedChildProcesses 

Return the rusage structure for all terminated child processes of the current 
process. 

Rationale 

The rusage C structure is used in support of the following UTek system calls: 

getrusage(2) 
wait3(2) 

Related Classes 

UTekSystemCall implements the system calls listed above. 
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View subclass: #ScreenView 

instanceVariableNames: 
classVariableNames: 
poolDictionaries: 
category: 


'DefaultModel ' 
'Interface-Support' 



Summary 

ScreenView is the view for the parts of the display screen that have no window on 
them. It responds to restore:, so that when views erase themselves, the 
background gets restored. Its model must respond to displayOn:filI:. An 
InfiniteForm whose patternForm is 16x16 (a halftone) makes a good model, 
because such a form quickly refreshes the screen. The default color is gray. 

The following message can be used as a sample to change the model of the current 
screenController. It will require you to provide a form by framing a section of the 
screen. 

ScreenController backgroundFromUser. 

Class Variables 

DefaultModel <lnfiniteForm> 

The default model for new screen views. New screen views are created 
upon opening a project. 



Instance Methods 

initialize-release 

initialize 

Specifies the default model for this view. Its controller is ScreenController. 

controller access 

defaultControilerClass 

Answer the class of Screen View's controller. 
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displaying 



display View 

Paint the Display using tine ScreenView's model. 

restore: rectangleCollection 

Redisplay those portions of the receiver that intersect rectangles within 
rectangleCollection. Answer an empty collection of rectangles, since the 
screen is everywhere. 



Class Methods 



examples 

bacl<groundFromUser 

Frame a small portion of the display and it will become the model for the 
background. 

dari<GrayBackground 

Change the background to dark gray. 

grayBackground 

Change the background form to gray. 

whiteBackground 

Change the background form to white. 

model accessing 

defauitModel 

Answer the default background model. If it is nil, set it to a grayMask (a 
16x1 6 form). 

defauitModel: aForm 

Change the background form to aForm. 

Rationale 

This class allows you to change the background on the screen to any pattern or 
mask that you prefer, individual projects can have their own unique background. 

Discussion 

Initialize-release protocol initializes the default model and the controller for a 
ScreenView. 
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Controller access protocol answers the controller for this class. 

Displaying protocol paints and restores the display. 

Examples contains several methods to change the background color (to white, gray, 
or dark gray) and one method that requires you to frame a small section of the 
display to become the model for the background. 

Model accessing protocol allows you to set the default model for the background to 
any form you choose. It also answers the default background or sets it to gray if it 
isn't already set. 

Examples 

See the methods in the metaclass examples message category for ideas on how to 
use this class. 

Related Classes 

Form 

InfiniteForm 

ScreenController 
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OS-Parameters 



ExternalBinaryData variableByteSubclass: #Sgttyb 


instance VariableNames: 


" 


classVariableNames: 


'EraseDatalndex FlagsDatalndex 




IspeedDatalndex KillDatalndex 




OspeedDatalndex ' 


pooIDictionaries: 


" 


category: 


'OS-Parameters' 



Summary 

Sgttyb provides creation and accessing protocol for the following C structure. 



struct sgttyb { 

char sgjspeed; 



} 



char 
char 
char 
short 



sg_ospeed; 
sg_erase; 
sg_kili; 
sgjiags; 



/♦ input speed */ 
/* output speed */ 
/♦ erase character ♦/ 
/* kill character */ 
/* mode flags */ 



The structure is documented \xx\fiQX tty{4) in the manual UTek Command Reference, 
Volume!. 

Class Variables 

EraseDatalndex 

FlagsDatalndex 

IspeedDatalndex 

KillDatalndex 

OspeedDatalndex 

Each C structure class variable holds the offset of a single field in the 
structure. The name of a class variable is constructed from a field name, 
stripped of Its prefix, with the string 'Datalndex' appended. For example, 
the class variable EraseDatalndex holds the offset of the "sg_erase" field. 
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Instance Methods 

accessing 



erase 

Return the value of the structure field named erase. 

erase: aCharacter 

Assign the argument, aCharacter, to the structure field named erase. 

flags 

Return the value of the structure field named flags. 

flags: anint 

Assign the argument, anInt, to the structure field named flags. 

ispeed 

Return the value of the structure field named ispeed. 

ispeed: anInt 

Assign the argument, anInt, to the structure field named ispeed. 

Ispeed: anInt ospeed: anotherint erase: aCharacter 
kill: kCharacter flags: lastlnt 
Assign values to all the fields of the structure. 

kill Return the value of the structure field named kill. 

kill: aCharacter 

Assign the argument, aCharacter, to the structure field named kill. 

ospeed 

Return the value of the structure field named ospeed. 

ospeed: anInt 

Assign the argument, anint, to the structure field named ospeed. 



printing 



printOn: aStream 

Print the receiver on aStream, 
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Class Methods 



• class initialization 

initialize 

Assign offset values to the class variables and define the size of the 
structure. 

instance creation 

default 

Return an instance containing the default characters. 

Rationale 

The structure is used in support of the following UTek system call: 
ioctlil) 

Related Classes 

UTekSystemCall implements the system call listed above. 
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Sockaddrin OS-Parameters 



ExternalBinaryData variableByteSubclass: #Sockaddrln 


instanceVariableNames: 


" 


classVariableNames: 


'AddrDatalndex FamilyDatalndex PortDatalndex 




ZeroDatalndex ZeroLength ' 


poolDictionaries: 


" 


category: 


'OS-Parameters' 



Summary 

Sockaddrin provides creation and accessing protocol for the following C structure. 

struct sockaddrjn { 

short sin_family; 

u_short sin_port; 

struct in_addr sin_addr; 

char sin_2ero[8]; 

} 

The structure Is documented under inet(4N) in the manual UTek Command 
Reference, Volume 2. It is used as an internet domain socket address. 

Class Variables 

AddrDatalndex 
FamilyDatalndex 
PortDatalndex 
ZeroDatalndex 

Each C structure class variable holds the offset of a single field in the 
structure. The name of a class variable is constructed from a field name, 
stripped of its prefix, with the string 'Datalndex' appended. For example, 
the class variable PortDatalndex holds the offset of the "sin_port" field. 

ZeroLength <lntegen> 

This variable holds the constant, 8, of the sin zero field. 
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Instance Methods 

accessing 
addr 



Return the value of the structure field named addr. 

addr: anInternetAddress 

Assign the argument, anInternetAddress, to the structure field named addr. 

port 

Return the value of the structure field named port. 

port: anint 

Assign the argument, anint, to the structure field named port. 

port: anint addr: anInternetAddress 

Assign values to all the fields of the structure. 



printing 



printOn: aStream 

Print the receiver on aStream. 



Class Methods 



class initialization 

initialize 

Assign offset values to the class variables and define the size of the 
structure. 

instance creation 

port: anint addr: anInternetAddress 

Return an instance with the values of the fields assigned. 
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Rationale 

This class is the C structure which holds an internet domain socket address. It 
holds the network address and the port number, for accessing processes such as 
ftp, telnet, and finger. The structure is used in support of the following UTek system 
calls: 

accept(2) 

bind(2) 

connect(2) 

getpeername(2) 

getsockname(2) 

recyfrom(2) 

sendto(2) 

Related Classes 

UTekSystemCall implements the system calls listed above. 
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ExternalBinatyData variableByteSubclass: #SockaddrUn 

instance VariableNames: 

classVariableNames: 'FamilyDatalndex PathDatalndex PathLength ' 

poolDictionaries: 

category: 'OS-Parameters' 



Summary 

SockaddrUn provides creation and accessing protocol for the following C structure. 

struct sockaddr_un { 

short sunjamily; /♦ AF_UNIX */ 

char sun_path[108]; /* path name */ 
} 

The structure is found in syslun.h. It is used as a UNIX domain socket address. 

Class Variables 

FamilyDatalndex 
PathDatalndex 

Each C structure class variable holds the offset of a single field in the 
structure. The name of a class variable is constructed from a field name, 
stripped of its prefix, with the string 'Datalndex' appended. For example, 
the class variable PathDatalndex holds the offset of the "sun_path" field. 

PathLength <lnteger> 

This variable holds the constant, 108, of the sun_path field. 

Instance Methods 

accessing 

family: anint path: aByteArray 

Assign values to all the fields of the structure. 
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path 

Return the value of the structure field named path. 

path: aString 

Assign values to all the fields of the structure. 



printing 



printOn: aStream 

Print the receiver on aStream. 



Class Methods 



class initialization 

initialize 

Assign offset values to the class variables and define the size of the 
structure. 

instance creation 

family: anint path: aByteArray 

Return an instance with the values of the fields assigned. 

path: aString 

Return an instance with the values of the fields assigned. 

Rationale 

This class represents the C structure which holds a UNIX domain socket address. It 
allows access to unrelated processes running on the local machine. The structure is 
used in support of the following UTel< system calls: 

accept(2) 

bind(2) 

connect(2) 

getpeername(2) 

getsockname(2) 

recyfrom(2) 

sendto(2) 

Related Classes 

UTel<SystemCall implements the system calls listed above. 



148 



Stat 



OS-Parameters 



ExtemalBinaryData variableByteSubdass: #Stat 


instance VariableNames: 


" 


classVariableNames: 


'AtimeDatalndex BIksizeDatalndex 




BlocksDatalndex CtimeDatalndex DevDatalndex 




GidDatalndex HostidOatalndex InoDatalndex 




ModeDatalndex MtimeDatalndex NlinkDatalndex 




RdevDatalndex SizeDatalndex SparelDatalndex 




Spare2DataIndex SpareSDatalndex 




Spare4Datalndex UidDatalndex ' 


pooIDictionaries: 


" 


category: 


'OS-Parameters' 



Summary 

Stat provides accessing protocol for the following C structure. 



struct Stat { 




devj 


st_dev; 


ino t 


St ino; 


unsigned short 


st_mode; 


short 


St nlink; 


short 


St uid; 


short 


st_gid; 


dev_t 


st_rdev; 


off t 


st_size; 


time t 


st_atime; 


int 


st_spare1 ; 


time t 


st_mtime; 


int 


st_spare2; 


time t 


st_ctime; 


int 


st_spare3; 


long 


st_blksize; 


long 


st_blocks; 


long 


st_hostid; 


long 


st_spare4; 



/* ID of device containing a directory entry 

for this file */ 

/* this inode's number */ 

/♦ file mode ♦/ 

/* number of hard links to the file ♦/ 

/* user ID of the file's owner */ 

/♦ group ID of the file's group ♦/ 

/* ID of device — this entry is defined only 

for character special or block special files */ 

/* total size of file */ 

/* time of last access */ 

/* time of last data modification */ 

/* time of last file status change */ 

/* optimal blocksize for file system I/O ops */ 
/♦ actual number of blocks allocated */ 
/♦ hostid of machine where file is located ♦/ 
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The structure is documented under stat(2) In the manual UTek Command Reference, 
Volume 2. 

Class Variables 

AtimeDatalndex 

BIksizeDatalndex 

BlocksDatalndex 

CtimeDatalndex 

DevDatalndex 

GidDatalndex 

HostidDatalndex 

InoDatalndex 

ModeDatalndex 

MtimeDatalndex 

NlinkDatalndex 

RdevDatalndex 

SizeDatalndex 

Sparel Dataindex 

Spare2Datalndex 

SpareSDatalndex 

Spare4Datalndex 

UidDatalndex 

Each C structure class variable holds the offset of a single field in the 
structure. The name of a class variable is constructed from a field name, 
stripped of its prefix, with the string 'Dataindex' appended. For example, 
the class variable AtimeDatalndex holds the offset of the "st atime" field. 
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Instance Methods 

accessing 



atime 

Return the value of the structure field named atime. 

biksize 

Return the value of the structure field named biksize, 

blocks 

Return the value of the structure field named blocks. 

ctime 

Return the value of the structure field named ctime. 

dev 

Return the value of the structure field named dev. 

gid Return the value of the structure field named gid. 

hostid 

Return the value of the structure field named hostid. 

ino Return the value of the structure field named ino. 

mode 

Return the value of the structure field named mode. 

mtime 

Return the value of the structure field named mtime. 

nlink 

Return the value of the structure field named nlink. 

rdev 

Return the value of the structure field named rdev. 

size 

Return the value of the structure field named size. 

sparel 

Return the value of the structure field named sparel. 

spare2 

Return the value of the structure field named spare2. 
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Spares 

Return the value of the structure field named spare3. 

spare4 

Return the value of the structure field named spare4. 

uid Return the value of the structure field named uid. 

accessing-status 

ifdir 

If the receiver is a status for a directory, return true. 



printing 



printOn: aStream 

Print the receiver on aStream. 



Class Methods 



class initialization 

initialize 

Assign offset values to the class variables and define the size of the 
structure. 

Rationale 

The structure is used in support of the following UTek system calls: 

fstat(2) 
lstat(2) 
stat(2) 

Related Classes 

UTel<SystemCaiI implements the system calls listed above. 
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Graphics-Support 



Object subclass: #StrikeFont 




instance VariableNames: 


'xTable glyphs name stopConditions type 




minAscii maxAscii maxWidth strikeLength ascent 




descent raster subscript superscript emphasis 




ascentForStdAsciiChars 




descentForStdAsciiChars ' 


classVariableNames: 


'ASCIICompatible DefauItStopConditions 




DefaultStopConditionsForMonospaceFonts 




FaceNames ' 


poolDictionaries: 


'TextConstants ' 


category: 


'Graphics-Support' 



Summary 

StrikeFonts are a compact encoding of a set of Forms corresponding to characters 
in the ASCII character set. Additional characters, other than standard ASCII, may 
be present depending upon the type of font. All the forms are placed side by side in 
a large form whose height is the font height, and whose width is the sum of all the 
character widths. The xTable gives the left x-coordinates of the sub-forms 
corresponding to the characters. 

Instance Variables 

ascent <lnteger> 

Maximum extent of characters above the baseline. 

ascentForStdAsciiChars <lnteger> 

Maximum extent of characters above the baseline for ASCII decimal 
equivalent 32 through 126. 

descent <lnteger> 

Maximum extent of characters below the baseline. 

descentForStdAsciiChars <lnteger> 

Maximum extent of characters below the baseline for ASCII decimal 
equivalent 32 through 126. 

emphasis <lnteger> 

This code indicates that the face is achieved synthetically by altering 
another face: O=none. 1=bold, 2=italic, 4=underline, 8=strike-out, 
16=subscript, and 32=superscript. 
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glyphs <Form> 

An instance of Form containing bits representing tlie entire set of 
cliaracters in this font. 

maxAscii <lnteger> 

Highest ASCII value supported by this font. 

maxWIdth <lnteger> 

Width of widest character. Not presently used, but may be for font 
modification. 

mInAscJI <lnteger> 

Lowest ASCII value supported by this font. 

name <String> 

Name of this font. 

raster <lnteger> 

Actual width of glyphs (strikeLength + 15 W 16), given Forms are padded to 
multiples of 16 bits. 

stopConditions <Array> 

Array at least as large as xTable with an entry for each character in the 
font. Nil indicates no special processing; any other entry causes special 
processing to be executed for the character (e.g., tab, linefeed) by the 
CompositionScanner. 

StrikeLength <lnteger> 
Width of glyphs. 

subscript <lnteger> 

Additional vertical offset relative to the baseline. 

superscript <lnteger> 

Additional vertical offset relative to the baseline. 

type <Integer> 

Code indicating font type: 

Code Font 



1 Tektronix monospaced 

2 Tektronix proportional 

3 Xerox 

n A font from other sources 



xTable <Array> 

Left x-coordinate of character sub-forms in glyphs. The xTable entry of a 
character is the answer from aCharacter asciiValue plus one. For example. 
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the left x-coordinate of $A is the 66th entry in the xTable of the default font 
in the default text style (in the standard image). 

Class Variables 

ASCIICompatible <integer> 

Constant used when the font is loaded to determine whether it is ASCII 
compatible (0 = unknown type, 1 = ASCII). 

DefaultStopConditions <Array> 

DefaultStopConditions is a class variable containing a stop condition entry 
for each character in a standard ASCII proportional font (type 2 or 3). 
Unless another stopCondition array is initialized when the StrikeFont is 
loaded, a newly created standard proportional StrikeFont's stopCondition 
array will refer to DefaultStopConditions. 

DefaultStopCondltionsForMonospaceFonts <Array> 

DefaultStopConditionsForMonospaceFonts is a class variable containing a 
stop condition entry for each character in a monospace font (type = 1 ). 
Unless another StopCondition array is initialized when the StrikeFont is 
loaded, a newly created standard monospace StrikeFont's stopCondition 
array will refer to DefaultStopConditionsForMonospaceFonts. 

FaceNames <Dictionary> 

Dictionary of valid face names (e.g., 'Bold', 'Bold Italic') and associated 
font name sub-strings (e.g., 'B', 'X'). 

Pool Dictionaries 

TextConstants 

A dictionary of symbols for non-printing characters, symbols related to text 
composition and text emphasis, and default values for text composition and 
text emphasis. 



Instance Methods 

initialize-release 



InltiallzeFrom: aFontFile 

Read a font from aFontFile which must be in Tektronix format. Return a 
StrikeFont or, in case of error, nil. 
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accessing 



ascent 

Answer the font's maximum extent of characters above the baseline. 

ascentForStdAsciiChars 

Answer the font's maximum extent of characters above the baseline for 
ASCII decimal equivalent 32 through 126. 

bottomLead: character 

Answer the amount of white space or leading imbedded in the character 
form at the bottom. 

characterForm: character 

Answer a Form copied out of the glyphs for this character. 

descent 

Answer the font's maximum extent of characters below the baseline. 

descentForStdAscilChars 

Answer the font's maximum extent of characters below the baseline for 
ASCII decimal equivalent 32 through 126. 

glyphs 

Answer a Form containing the bits representing the characters of the 
receiver. 

height 

Answer the height of the font — the total of maximum extents of characters 
above and below the baseline. 

leadinfo 

If this Is a fixed pitch font, compute the leading by adding the font's 
imbedded top and bottom leading. If this is a proportional font, return a 
recommended leading adjusted according to the height of the font. If the 
font size is not standard, return a nominal leading. 

maxAscii 

Answer the integer that is the last ASCII character value of the receiver. 

maxWIdth 

Answer the integer that is the width of the receiver's widest character. 

minAscii 

Answer the integer that is the first ASCII character value of the receiver. 
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name 

Answer the receiver's name. 

name: aString 

Set the receiver's name. 

raster 

Answer an integer that specifies the layout of the glyphs' form. 

stopConditions 

Answer the array of selectors to be performed in scanning text made up of 
the receiver's characters. 

subscript 

Answer an integer that is the additional vertical offset relative to the 
baseline for positioning characters as subscripts. 

subscript: aninteger 

Set the subscript instance variable that is the additional vertical offset 
relative to the baseline for positioning characters as subscripts. 

superscript 

Answer an integer that is the additional vertical offset relative to the 
baseline for positioning characters as superscripts. 

superscript: aninteger 

Set the superscript instance variable that is the additional vertical offset 
relative to the baseline for positioning characters as superscripts. 

tIghtLeadinfo 

If this is a fixed pitch font, compute the leading by adding the font's 
imbedded top and bottom leading. If this is a proportional font, return a 
minimum recommended leading of 4. 

topLead: character 

Answer the amount of white space or leading imbedded at the top of the 
character form. 

type 

Answer the receiver's compatibility mode. 

type: aninteger 

Set the receiver's compatibility mode. 
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unprintableCharacter 

Return a character that represents all unprintable characters In the font. 

wIdthOf: aCharacter 

Answer the width of the argument aCharacter. 

xTable 

Answer an array of the left x-coordinates of characters in glyphs. 

converting 

asTextStyle 

Return a TextStyle composed of the StrikeFont which received this 
message. 



displaying 



characters: anlnterval in: sourceString displayAt: aPoint 

clippedBy: clippingRectangle rule: rulelnteger mask: aForm 

Simple, slow method for displaying a line of characters. No wrap-around is 

handled. 

composeWord: aTextLinelnterval In: sourceString beginningAt: xlnteger 
Return the sum of the widths of characters in sourceString starting at 
xlnteger for aTextLinelnterval count. This method is similar to performance 
of the scanning primitive, but ignores stop conditions. 

displayLine: aString at: aPoint 

Display the characters in aString, starting at position aPoint. 



emphasis 



emphasis 

Answer the integer code for one of the following: synthetic bold, italic, 
underline, or strike-out. If the font has no synthetic emphasis, a zero value 
will be returned. 

emphasis: code 

Set the emphasis code to synthesize one of these: bold=1 , italic=2, 
underlined=4, struck out=8, subscrlpt=16, superscript=32. Zero means no 
synthetic emphasis. 
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emphasized: code 

Answer a copy of the receiver, and set the returned StrikeFont's emphasis 
to code. 

emphasized: code named: aString 

Answer a copy of the receiver, with emphasis set to code and name set to 
aString. 

printing 

prlntOn: aStream 

Print the name and emphasis of this font on aStream. 

write On: aStream 

Write out the representation of this font on aStream using the Tektronix font 
file format. 

writeOnFile: aString 

Create a Tektronix font format file named aString. Types 1 (monospace), 2 
(proportional) and 3 (Xerox) can be reread with an instance creation 
message without a warning notice in the System Transcript. 

testing 

checkCharacter: character 

Return a character if it is a valid printable character in the receiver; 
otherwise return the default character for unprintable characters. 

isFixedPitch 

Answer true if all legal characters of the font are the same width. 

isVirtua! 

Since the receiver is not a VirtualStrikeFont, return false. 



Class Methods 



class initialization 

initialize 

Set up FaceNames dictionary and the default stop conditions. 
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fileln-Out 

readAII: aFontDirectoryName 

Read in all the fonts in aFontDirectoryName. These fonts are assumed to 
be in Tektronix format. Skip over files with illegal names, and files that 
return 'nil' when read. 

readFrom: aFontFileStream 

Read in a font from aFontFileStream. This font is assumed to be in 
Tektronix format. 

Rationale 

StrikeFont enables characters to display, so that when you type on the keyboard, 
graphic representations of the ASCII codes will echo to the display. Since Smalltalk 
is graphically oriented, instances of StrikeFont allow you to choose among 
collections of characters with different physical appearances. 

Background 

Terminology 

Before the Smalltalk implementation of fonts is discussed, you might find it helpful to 
understand some of the terms used in the descriptions of the Graphics — Support 
classes in this manual. 

FacB is the emphatic property of a font. For Tektronix and Xerox fonts, the last one 
or two characters in the StrikeFont name will signify the face, as discussed 
later under "StrikeFont Names". Face is represented in StrikeFont by the 
emphasis instance variable when it is necessary to synthesize a particular 
face. Basal is the "base" or standard face from which other fonts are 
synthesized. Synthesizing is discussed below under "Available Fonts". 

Family refers to the basic look of a set of characters that makes it distinguishable 
from another set. Family is the intrinsic property of a font. Families are 
named and frequently protected by copyright. Examples include 
"Helvetica" and "Pellucida". The array of fonts which are returned by the 
message to the global TextStylelVIanager 

StyleManager stylcName-.'Pellucida Serif 10-12' baseNames: 
#('PellucidaSeriflO"PeUucidaSerifl2') 

will all belong to the "Pellucida" family. Usually, the fonts in a TextStyie 
will all be in one family, although you may mix families in a TextStyie. This 
manual was produced using fonts in three families, "Helvetica", 
"TimesRoman", and "Courier". 
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A font, in the days before computer typesetting, was a set of letters and symbols, 
such as punctuation, that a printer would assemble in lines, coat with ink, 
and press — to put impressions on paper. In Smalltalk, a font is an 
instance of StrikeFont, a collection of Forms with the bitmaps for each 
character and symbol available in the font. 

The sizeoi a font is measured vertically in points in the world of printing. A point is 
1/72 of an inch. For historical reasons, the point size has been retained in 
the font names in Smalltalk, although the size on the display will be an 
approximation of point size. To draw a parallel to a Smalltalk instance 
variable, the ascent of a StrikeFont is close to the "size" in the 
corresponding font file's name. 

Leading is the sum, in points, of the font size and the white space below a line of 
printed text. The scale of leading in Smalltalk is pixels, not points. In 
printing the spoken phrase "10 on 12" would indicate 10 point type on 12 
point leading. Smalltalk's parallel to leading is the JineGrld in a TextStyle. 
Several StrikeFont accessing methods answer the amount of white space 
imbedded at the top or bottom of a character, answer the recommended 
leading for a font, or the minimum leading for a font. Fixed pitch fonts in 
this product have "leading" imbedded at the top and bottom of the forms in 
glyphs, so no extra leading is recommended when you create a TextStyle 
with the "Pellucida Typewriter" family. 

Font Files 

The Smalltalk fonts are derived from font files in the Utek operating system residing 
in the directory name returned by 

OS fontDirectory fullName. 

This directory contains quite a number of font files. The files having Pellucida and 
Xerox as part of their names are completely compatible with Tektronix Smalltalk. By 
compatible is meant that the files are in Tektronix font file format, and the methods 
for installing fonts will work properly. Other fonts in this directory may be loaded in 
the FontManager, but they may have a character set that differs from familar ones. 

The font files are grouped into font families: Pellucida Sans-Serif, Pellucida Serif, 
Pellucida Typewriter, Xerox Sans-Serif, and Xerox Serif. The Pellucida Sans-Serif, 
Pellucida Serif, and Xerox families are proportionally spaced (individual characters 
within the same font have varying widths); the Pellucida Typewriter family is 
monospaced (individual characters within the same font have the same width). The 
Pellucida families have been specially designed for Tektronix Smalltalk; the Xerox 
families are the standard Smalltalk-80 Version 2 fonts. 
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Reading and Writing Font Files 

StrikeFont has methods for reading and writing Tektronix font files. Note that 
whenever Smalltalk reads a Tektronix font file, it switches the character position of 
the up arrow character (T) and left arrow («-) with the caret (*) and underscore (_) 
characters. If you ask the character T, for instance, what its ascliValue is you get 
94. 

The method to write a StrikeFont takes care to switch the positions of the T, <-, *, 
and _ characters if the type of the StrikeFont is either 1 (Tektronix monospaced) or 
2 (Tektronix proportionally spaced). This ensures that the proportional or 
monospaced fonts written by Smalltalk have consistent ordering for standard ASCII 
characters. 

Available Fonts 

In some cases a face other than Basal is created for an instance of StrikeFont by 
synthesizing it from another face. Synthesizing involves bitmap manipulation, for 
example, shearing Basal to create Italic, copying and offsetting Basal to create Bold. 
The underlined fonts are synthesized from their corresponding font, for example. 
Bold Underlined is synthesized from Bold. Non-synthetic faces usually have a better 
appearance than synthetic faces. 

There are 64 non-synthetic Pellucida fonts. The Pellucida sans-serif and serif fonts 
are available in four non-synthetic faces (Basal, Bold, Italic, and Boldltalic) and 
seven sizes (8, 10, 12, 14, 18, 24, and 36 point). The Pellucida Typewriter fonts are 
available in two non-synthetic faces (Basal and Bold) and four sizes (10, 12, 16, and 
18 point). 

There are 1 1 non-synthetic Xerox fonts. The serif and sans-serif fonts are available 
in 10 and 12 point size and Basal, Bold, and Italic. The sans-serif 10 point Italic, 
however, is synthesized. 

Font File Names 

Font file names are made up of four parts: 

• A name descriptive of the family the font belongs to. Examples are 
PellucidaSans-Serif, PellucidaSerif, PellucidaTypewriter, and XeroxSans-Serif. 

• The point size of the font. This is usually an even number from 8 to 36. 

• Optionally, one of the following emphasis characters: B standing for bold, /for 
italic, and X for bold italic. Absence of one of those three characters denotes 
basal. 
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• The required suffix .font, denoting a font file. 

Note that some font files are not entirely compatible (a clue is that they do not have 
Pellucida or Xerox in their name). Examples are BertrandVariablell.font, 
MagnoliaFixedl2.font, and MicroS.font. The primary incompatibility of these files is 
that underscore is not mapped to the Smalltalk assignment (left) arrow and the caret 
(shift-6) is not mapped to the Smalltalk return (up) arrow. In general, even fonts with 
compatibility code other than 1 , 2, or 3 can be loaded as StrikeFonts. 

StrikeFont Names 

The names of StrikeFonts are closely related to font file names, however, 
StrikeFont names are not constructed from font file names themselves, but from 
information in a font file. 

The name of a StrikeFont is a String with three components (family, size, and face) 
and no imbedded spaces. The family component is the family name with spaces 
removed; the size component is the printString of the numeric size; and the face 
component is a String of length zero, one, or two signifying the face. The supported 
face codes are "" (Basal), B (Bold), I (Italic), X (Boldltalic), U (Basal Underlined), BU 
(Bold Underlined), lU (Italic Underlined), and XU (Boldltalic Underlined). The face 
codes for synthetic fonts are not taken from the font file; for example, the U for 
"underlined" does not appear in the font file. Examples of names include 
'PellucidaSans-SerifS', 'XeroxSeriflZ!', and 'PellucidaTypewriter18Br. The 
underlined face codes are assigned when a styIeName:baseNames: message is 
sent to the global StyieManager to create an instance of TextStyle. 

Discussion 

Class Protocol 

Class initialization contains one method to initialize the class; it is not a message a 
user would typically send. 

Fileln-Out methods file in StrikeFonts from the fonts directory on the disk — either 
one font or all the fonts in a specified directory. The recommended way to install 
fonts is to use a TextStyleManager accessing message. 

Instance Protocol 

You are not likely to use the initialize-release method InitlalizeFrom:. It is called by 
the class method readFrom:. 
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Accessing methods return the values of instance variables. One method, 
character Form:, returns a form with a sub-form from glyphs; you could use the bit 
editor to modify the form or simply display the single character. You can set the 
name and type of a StrikeFont, and the amount to subscript and superscript the 
characters. You shouldn't change the type of a StrikeFont unless you have 
modified it, for example, by adding or removing characters. 

A converting method converts a StrikeFont to a TextStyle and returns the 
TextStyle. 

Displaying methods enable you to compose and display characters without including 
them in typical displayable objects such as a Paragraph. You can determine the 
width of part of a string, display part or all of a string in a form, or display a string at 
a point you specify. The two methods for displaying do not wrap the characters at 
the right boundary of the form or display. 

Emphasis methods answer or set the emphasis of the StrikeFont, return a copy of 
the StrikeFont with emphasis set to the previous value plus the specified additional 
amount, and return a copy with the specified additional emphasis and a specified 
name. 

Printing method printOn: prints the class name, name instance variable, and 
emphasis instance variable of a StrikeFont on a stream. Two methods, wrIteOn: 
and wrIteOnFile:, write the StrikeFont on a stream or a disk file, respectively. The 
font is written in a form which is readable by the method which loads fonts. 

Testing methods check whether a character is within the ASCII range of the 
StrikeFont and answer whether all the characters in the StrikeFont are the same 
width (fixed pitch). 

Examples 

The code below shows one way to insert in a string a character for which there is no 
key on your keyboard. To see what Character value: 2 is, try executing the code in a 
workspace. 

s<— This is a test'. 

s at: 15 put: (Character value:2). 

s asDisplayText displayAt: Sensor waitClickButton. 

The tables of characters available in the Pellucida fonts show you the argument to 
value: to create an instance of the character. The argument should be the number 
in the box with the character you want. (See tables at the end of this class.) 
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Related Classes 

StrlkeFontManager 
TextStyle 
TextStyleManager 
VirtualStrlkeFont 
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Tektronix Proportional Fonts 

Pellucida Serif and Sans-Serif 

(Compatibility Code = 2) 

Ciiaracters 0-127 
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The number in the lower left comer of each cell is the ASCII decimal 
value (returned by sending the message asciiVaiue to the Character). 
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Tektronix Monospace Font 

Pellucida Typewriter 

(Compatibility Code =1 ) 

Characters 0-127 
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The number in the lower left corner of each cell is the ASCII decimal value 
(returned by sending the message asciiValue to the Character). 
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Tektronix Monospace Font 

Pellucida Typewriter 

(Compatibility Code = 1 ) 

Characters 128-255 
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The number in the lower left corner of each cell is the ASCII decimal value 
(returned by sending the message asciiValue to the Character). 
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Dictionary variableSubclass: 


#StrikeFontManager 


instance VariabieNames: 


" 


classVariableNames: 


'Emphases ' 


poolDictionaries: 


TextConstants ' 


category: 


'Grapiiics-Support' 



Summary 

StrikeFontManager is a Dictionary wliich maps instances of StrikeFont and 
VirtualStrikeFont to String names. 

Class Variables 

Empliases <Dictionary> 

Contains associations between a valid emphasis string and its 
corresponding emphasis code. 

Pool Dictionaries 

TextConstants 

A dictionary of symbols for non-printing characters, symbols related to text 
composition and text emphasis, and default values for text composition and 
text emphasis. 

Instance Methods 

accessing 

at: aString put: aStrikeFont 

Install aStrikeFont named aString. 

familySizeFace: name 

Return an array with name <String>, pointSize <lnteger>, and 
emphasis <lnteger>. 

fontDirectoryincludesFontFileNamed: aString 

Return true if the file named aString is in the font directory. 
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fontFileStream: aString 

Return a file stream for the font named aString. 

fontNames: anArray 

Answer an Array of StrikeFonts corresponding to anArray of String names. 
Load or synthesize the fonts, if necessary, and register the elements of the 
array in the FontManager. 

install: aString 

Install the font named aString if necessary. Load or synthesize the font if 
necessary. Complain if the font is missing. 

install: aString ifAbsent: aBlock 

Install the font named aString if necessary. Load or synthesize the font if 
necessary. Answer the result of evaluating aBlock if the font is missing. 

virtualFontNames: anArray 

Answer an Array of StrikeFonts or VirtualStrikeFonts corresponding to 
anArray of font names, and register the elements of the array in the 
FontManager. 

virtuallylnstall: aFontName 

Virtually install the font named aFontName if necessary. Create virtual 
fonts to load or to synthesize the font if necessary. Complain if the font 
cannot be constructed. 



Class Methods 



class initialization 

initialize 

Install the global FontManager, if none exists. Create an Emphases 
dictionary of associations between the emphasis string in a font name and 
the corresponding emphasis code. 

Rationale 

StrikeFontManager insures that all the StrikeFonts you reference are recorded in 
one place. Once a TextStyle is installed and used, its StrikeFonts are recorded in 
the StrikeFontManager. The StrikeFontManager keeps track of whether a 
StrikeFont has been loaded in the image or whether it is a VirtualStrikeFont and 
needs to be loaded when it is used the first time. When a StrikeFont is registered 
with the manager, it is accessible throughout the system. There are 64 fonts of 
compatibility types 1,2, and 3 plus several other fonts in the directory returned by 
OS fontDirectory. When you bring up the standard image the first time by typing 
Smalltalk, the FontManager has the StrikeFonts needed by the default text 
style. 



170 



StrikeFontManager Graphics-Support 



Discussion 

The global FontManager is used in Smalltalk code to refer to the one instance of 
StrikeFontManager that will exist at all times. It is possible to create a new 
instance of this class, but you are not likely to do so. 

Instance Protocol 

Accessing 

Various methods are provided to access a StrikeFont in the dictionary, put a 
StrikeFont into the dictionary, and return an array of StrikeFonts after loading or 
synthesizing them (if necessary). You can register a StrikeFont without actually 
loading it into the image by sending the message virtuallylnstall:. 

You are more likely to use a TextStyleManager instance creation message to load 
a StrikeFont than to use one of these accessing messages. It is reasonable, 
however, to add a font to the dictionary under these cases: 

• You have modified a font, for example, by changing characters. 

• You have modified a font by changing its emphasis (extra bold underlined, for 
example). 

• You rename the font. 

You might have occasion to use the messages virtualFontNames:, fontNames:, 
and Install:, FontNames: guarantees that the fonts are installed in the image — 
this makes your image bigger. Install: is easier to use than the other two since it 
takes a string, not an array, as an argument. 

Related Classes 

StrikeFont 
TextStyle 
TextStyleManager 
VIrtualStrikeFont 



Tektronix Smalltalk Reference Manual 1 71 



172 



StructOutputTable System-Support 



Object subclass: #StructOutputTabIe 

instanceVariableNames: 'globalDict mapArray idCount 

class VariableNames: 

poolDictionaries: 

category: 'System-Support' 



Summary 

StructOutputTable is a table used to store mappings for an object. This mapping 
detects and preserves the cycles of circular objects. This table is used in the 
process of storing objects in an external format (called a structure), usually invoked 
by the message storeStructureOn: or storeStructureOnFile:. 

Instance Variables 

globalDict <Dictionary> 

A dictionary containing all unique values in the Smalltalk dictionary. 
Because these values are unique for each Smalltalk image, they are not 
written out. 

IdCount <lnteger> 

This instance variable is used to assign identification numbers to objects as 
they are written out. It is incremented as each new object gets an 
identification number assigned. 

mapArray <Array> 

An array of subcollections pairing the identification number derived from 
idCount with the object to which it is assigned. This pairing allows 
StructOutputTable to reference previously written objects instead of 
rewriting them, thus allowing the methods that write structures to deal with 
circularity. 



Instance Methods 

initialize-release 



new: arraySize globalDict: diet 
initialize the receiver. 
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accessing 



idOfElement: anObject jfNew: aBlock 

Answer the integer ID of anObject in the receiver's structure, evaluating 
aBlock if the object has not been previously encountered. 

if: anObject isGlobal: aBlock 

Evaluate aBlock if anObject is in the receiver's global dictionary. 



Class Methods 

instance creation 

new 

Answer a new instance of the receiver. 

Rationale 

The Smalltalk compiler has a limit on the size of objects it can reconstruct. Also, 
methods which rely on the compiler cannot recognize the circularity of objects. 
StructOutputTable provides a means for objects exceeding the size limit, or 
circular objects, to be stored externally and transferred between images. 

Background 

The messages fileOut: and fileln: can only be used with objects in a specific 
format. This format is one the compiler can read. 

Other methods which use the compiler format, such as storeOn:, cannot correctly 
file circular objects into or out of an image, because they do not keep track of which 
objects they have already handled. Objects can contain references (direct or 
indirect) to themselves. This circularity can send these methods into an infinite loop. 

Unlike compiler-based methods, the messages storeStructureOn: and 
readStructureFrom: make use of StructOutputTable to keep track of each 
structure as it is processed. Using this class, it is possible to move large circular 
objects into and out of an image. 

Discussion 

Discussion of the methods for copying Smalltalk structures may be found in 
Section 5, Programming in Smalltalk, of the manualTektronix Smalltalk Users. 

The class protocol instance creation includes one method which returns a new 
instance of the receiver, ready for use by the structure-storing methods. 
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The instance protocol iniiialize-release includes one method which creates a new 
array and reads the Smalltalk global variables into the instance variable globalDlct. 
It is called by the instance creation method. 

The instance protocol accessing includes the method IdOfElementilfNew: which 
evaluates whether an object has been encountered previously, if it has, it returns 
the identification number of the object. If it has not, it creates a unique identification 
number for the object passed in and stores the object-ID pair in the mapArray. This 
is how StructOutputTable keeps track of circularities. Accessing also includes the 
method If:lsGlobal: which determines if the object is in the global dictionary. If it is, 
the method evaluates the block passed in. These methods are called every time an 
object that is part of the structure is written. 

Examples 

Forms can be written in a format readable by the compiler, using the message 
storeOn:, however, they can also be written in structure format. The following 
example code uses the method storeStructureOn: to write a Form out to the disk, 
and the method readStructureFrom: to read the Form back into the image. It can 
be executed in a workspace. In doing so, the class StructOutputTable is used. 

aFileStrcam <— Disk file: 'example.stnict'. 

Form fromUser storeStructureOn: aFilcStream. "write it out" 

aFileStream reset, "move the file pointer back to the start" 

newForm <— Object readStructureFrom: aFileStream. "read in" 

aFileStream close. "clean up" 

newForm display "prove that it worked" 

Related Classes 

Methods which write structures using StructOutputTable are implemented in class 
Object. Object is also the class which contains methods to read the structures. 
Classes with unusual format, such as ContextPart, override certain internal 
methods. 
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ExternalPointerData subclass: #StructureArray 

instance VariableNames: 'numberOfElements 

classVariableNames: 

poolDictionaries: 

category: 'OS-Parameters' 


elementClass ' 



Summary 

StructureArray represents an array of ExternalData structures which may contain 
embedded pointers. Each element must be an instance of the same structure. 
StructureArray provides protocol for accessing and updating elements and protocol 
for creating instances. 

Subclasses can be made to provide protocol for accessing, by name, fields from an 
element of an instance. 

Instance Variables 

elementClass <Class> 

The class of each element of the array. 

numberOfElements <lnteger> 

The number of elements in the array. 



Instance Methods 

accessing 



at: an Index 

Return the instance of elementClass at anindex. 

at: anindex put: anElem 

Update the receiver's element at anindex with anElem. 

elementClass 

Return the class of elements of the receiver. 

elementNumberOfPolnters 

Answer the number of pointers in each element. 

elementPointersSIze 

Answer the pointersSize of each element. 
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elementSize 

Answer the size of each element. 

numberOfElements 

Answer the number of elements in the receiver. 

size 

Return the size of the receiver. 



Class Methods 



instance creation 



new: numberOfElems class: aClass 

Return an instance capable of holding numberOfElems elements of class, 
aClass. 

Rationale 

StructureArray is used by the system call class for your operating system to pass 
arguments to system calls which use arrays of structures. Examples of such system 
calls include readv(2) and writev(2). 

Related Classes 

UTekSystemCall uses this class. 
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Object subclass: #Subtask 




jnstanceVariableNames: 


'accessProtect arguments environment 




exceptionValue InitBlock priority program status 




taskID terminateBlock terminationValue 




waitSemaphore ' 


class VariableNames: 


" 


poolDlctionaries: 


" 


category: 


'OS-Interface' 



Summary 

An instance of Subtask represents a spawned operating system task. Its parent 
task is the Smalltalk task. For clarity, threads of control in the operating system are 
referred to as "tasks", and threads of control in Smalltalk are referred to as 
"processes". Subtask contains protocol for testing and controlling the spawned 
task. A subtask can be waited for in a manner which suspends the entire Smalltalk 
parent task, or in a manner which suspends only the controlling Smalltalk process. 
The Subtask metaclass contains protocol for the management of spawned 
subtasks. 

Instance Variables 

accessProtect <Semaphore> 

A semaphore used to protect accessing and setting of the status instance 
variable. 

arguments <OrderedCollection> 

A collection of strings, each of which is an argument to the program. 

environment <Dictionary> 

A dictionary of operating system environment variables, keyed by 
environment variable. Dictionary values are the values of the environment 
variables. 

exceptionValue <lnteger> 

This instance variable contains the interrupt number of the signal causing 
termination. Non-zero values represent error conditions. 

InitBlock <Block> 

A block to be executed between the fork call and the exec call. Usually this 
block involves signals and communication. 
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priority <lnteger> 

An integer representing \he operating system priority of tlie subtask. 

program <String> 

A string containing the path of the program to be executed. 

status <Symbol> 

A symbol indicating the status of the task. Possible values: 
nil 

#running 

#terminatedNormally 
#waitedOn 
#terminationSignaled 
#te rm i n ated With Cod e 
#terminatedWithSignal 
#nonexistent. 



Old State 


Transition State Changes 

Cause of Change New State 


nil 


start 


#running 


#runnlng 


wait 


#waitedOn 


#running 
#waitedOn 


successful interrupts 


#terminationSignaled 


#waitedOn 


exit status > 

signal status > 

exit and signal status =0 


#terminatedWithCode 

#terminatedWithSignal 

#terminatedNormally 


any 


snapshot 


#nonexistent 



taskID <lnteger> 

A unique identifying number assigned by the operating system. 

termlnateBlock <BlockContext> 

A block containing code to terminate the spawned subtask. A value of nil 
means terminate using the default action, sending a terminate Interrupt. 

termlnationValue <lnteger> 

This instance variable represents the code assigned by the exit system 
call. Non-zero values represent error conditions. 

waltSemaphore <Semaphore> 

A semaphore used to block the initiating process until the child task has 
terminated. 
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Instance Methods 

initialize-release 



initialize 

Set the subtask data to reflect the parent's environment. 

release 

Remove the receiver from the list of scheduled subtasks. 



accessing 



arguments 

Answer an OrderedCollection of arguments used in invoking this subtask. 

enhancedPriority 

Set the priority of the subtask to the highest possible priority. 

environment 

Answer the environment for this subtask in a dictionary format. 

environment: envDictionary 

Store the environment variables for this subtask. See 'environment 
variables' protocol in the metaclass. 

priority 

Answer the absolute priority of the subtask, 

priority: aPriority 

Set the priority of the subtask. 

program 

Answer the name of the executable program. 

status 

Answer the status of the receiver. Access with the protocol critical: to 
prevent inconsistencies in the status instance variable. 

taskID 

Answer an identifying unique integer assigned by the operating sytem. 

terminateBiock 

Answer the block that specifies the receiver's termination. 

terminateBiock: aBlock 

Record a block that allows the receiver to terminate in its own manner. 
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controlling 



Interrupt: anInterruptID 

Send an interrupt to my task. AnInterruptID is a system dependent integer 
indicating whicfi interrupt to send. The usual result of an interrupt is task 
termination. 

start 

Start the receiver by spawning a child, executing code to set up the child 
task (mainly communication and signal processing), and executing the 
program. If the execute fails terminate the child task. The child task will 
inherit the priority of the Smalltalk process. 

terminate 

Attempt to terminate the receiver's task in a manner which can be 
intercepted, 

termlnateUncondltlonally 

Terminate this task unconditionally. 

wait 

Wait for the receiver to terminate. 

waitWithSmalltalkSuspended 

Bypassing the dead child signal management, a wait system call is made. 
This call suspends the execution of the Smalltalk task. The list of 
scheduled subtasks is updated accordingly and the status of the 
termination is recorded for each child process until the receiver's subtask is 
found. This method replaces the use of the wait message, and is designed 
for use with non-interactive tasks that require the shutting down of the 
Smalltalk process for efficiency. 

copying 

copy 

Inappropriate for a Subtask. 

testing 

abnormalTermlnation 

Answer true if the status indicates abnormal termination, otherwise false. 

is Active 

Answer a boolean indicating if the receiver is running. 

IsNonExistent 

Answer a boolean indicating if the receiver's task is not present. 
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isTermlnated 

Answer a boolean indicating if the receiver has been terminated. 

notTerminated 

Answer a boolean indicating if the receiver has not been terminated. 



Subtask class 

instanceVariableNames: 'brokenPipesProcess scheduledSubtasks 

scheduledSubtasksAccessProtect 
unscheduledSubtasks waitProcess ' 



Subtask class — Instance Variables 

brokenPipesProcess <Process> 

This process runs forever, forking error notifiers upon signal receipt. 

scheduledSubtasks <Dictionary> 

Contains all the current subtasks keyed by tasklD. Subtasks are added to 
the list when started. Management of these tasks is done by the metaclass. 

scheduledSubtasksAccessProtect <Semaphore> 

Semaphore for mutual exclusion to protect accessing of list of currently 
scheduledSubtasks. 

unscheduledSubtasks <Dictionary> 

Contains unscheduled subtask termination information keyed by tasklD. 
This information, in the form of an executed wait system call, is collected 
and saved by the subtask management system. It is produced when a task 
dies, and it is not in the scheduled task list. 

waitProcess <Process> 

This process runs forever. Each time a "dead child" signal is received, a 
wait system call is made and the subtask management information 
updated. 



Class Methods 



class initialization 

initialize 

Create the accessing semaphore. Using the accessing semaphore, create 
a new dictionary of scheduled subtasks. 
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install 

This method is invoked when resuming after a snapshot. When resuming, 
connections to the task controlling and signaling mechanisms in the 
operating system must be re-established. Create these connections by 
forking processes to catch the dead child signal and the broken pipe signal. 
Also, create and initialize a new list of scheduled subtasks. 

installBrokenPipeProcess 

Install a process to catch broken pipe signals. Each time the signal is 
received, fork an error notifier. 

installSubtaskTerminationProcess 

Install a process to monitor spawned subtasks. If a signal indicating a child 
task termination is received, update the current data about spawned 
subtasks. If possible (wait call is non-blocking), continue updating until 
there are no more terminated subtasks. 

environment variables 

currentEnvironment 

Answer the current environment. For modification on a per subtask basis, 
senders should copy. 

InitiallzeEnvironment 

Initialize the internal record of the environment with which this image was 
invoked. 

instance creation 

fork: commandName then: aBlock 

Return a new instance of Subtask containing all the necessary information 
to execute the subtask. There are no arguments and the initialization block 
is empty. 

fork: commandName wIthArguments: arguments 

Return a new instance of Subtask containing all the necessary information 
to execute the subtask. Arguments is an OrderedCollection of arguments 
to the executable program specified by commandName. The initialization 
block is empty. 

fork: commandName wIthArguments: arguments standardin: in 
standardOut: out standard Error: err 

Return a new instance of Subtask containing all the necessary information 
to execute the subtask. Arguments is an OrderedCollection of arguments 
to the executable program specified by commandName. Three pipes are 
specified by the arguments in, out and err. Unused ends of the pipes are 
closed in the child process only. Senders must close the pipes for the 
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parent task. 

fork: commandName withArguments: arguments standardin: in 
standardOutAndError: out 

Return a new instance of Subtask containing all the necessary information 
to execute the subtask. Arguments is an OrderedCollection of arguments 
to the executable program specified by commandName. Two pipes are 
specified by the arguments in and out. Unused ends of the pipes are 
closed in the child process only. Senders must close the pipes for the 
parent task. 

fork: commandName withArguments: arguments then: aBlock 

Return a new instance of Subtask containing all the necessary information 
to execute the subtask. Arguments is an OrderedCollection of arguments 
to the executable program specified by commandName. ABlock is an 
initialization block executed by the spawned task upon startup. 

fork: commandName withArguments: arguments wIthEnv: anEnvironment 
then: aBlock 

Return a new instance of Subtask containing all the necessary information 
to execute the subtask plus specification of a list of environment variables. 
Arguments is an OrderedCollection of arguments to the executable 
program specified by commandName. ABlock is an initialization block 
executed by the spawned task upon startup. 

scheduled subtasks 

addSubtask: aSubtask 

Add a subtask to the dictionary of scheduled subtasks. Check the 
unscheduled subtask list to see if the task terminated before this method 
was called. If it terminated, update the task accordingly. 

addUnscheduledSubtask: aSubtaskID with: syscall 
Add a subtask to the list of unscheduled subtasks. 

iocateSubtask: aSubtasklO 

Given a subtask's ID, answer the subtask object stored in the dictionary of 
subtasks. 

removeSubtask: aSubtask 

Remove a subtask from the dictionary of subtasks. 

scheduledSubtasks 

Answer a dictionary of subtasks, keyed by subtask ID. 
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task management 

markAndSignalAII 

Mark the status #nonexistent and signal the wait semaphore of each 
previously scheduled subtask. This method is used when restoring after a 
snapshot. 

terminate: aTask 

Terminate aTask and remove it from the task list. 

terminateAli 

Terminate all the scheduled tasks and remove them from the task list. 

terminateUnconditionally: aTask 

Terminate the spawned task and remove it from the task list. 

Rationale 

Tektronix Smalltalk adds support for subtasks to make the job of creating, running, 
and communicating with the subtasks straightforward. Interfaces to operating 
system signals, program parameters, environment variables, and subtask priorities 
are also supported. 

Background 

Multi-tasking 

Most operating systems support multi-tasking. To the operating system, your 
running Smalltalk program is another task. Although Smalltalk has its own 
processes, Smalltalk can also create and communicate with operating system tasks. 

Operating system subtasks provide access to other executable programs. By using 
the class Subtask, you can create a child task so that you can use some resource 
— an operating system command, or a program you have written in the C language, 
etc. — outside of the Smalltalk process. 

By spawning new tasks, multi-tasking is accessible without leaving the Smalltalk 
environment. A newly spawned task is called a child task or a subtask. The original 
task is referred to as the parent task. The child task is a "copy" of the parent task — 
it shares resources with the parent task. Since only one task can execute at a time, 
CPU time is also shared, initially in a predetermined fashion. Common practice is 
for the spawned child task to perform some chore, and then report back to the 
parent task. After reporting, the child task terminates. A parent may choose to 
relinquish use of the CPU until a subtask terminates. It does this by an operation 
called waiting. While waiting, the parent task is blocked and cannot do anything 
else until the child task terminates. 
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The child task's chore is often accomplished by finding some other program to do 
the work. The use of this other program is known as an exec operation (for 
execute). In an exec operation, the spawned task "turns itself into" the other 
program. 

Pipes 

A pipe is used to convey data from one process (task) to another. Pipes are data 
structures set up in computer memory to be transient, even though they share other 
characteristics with files. 

Frequently, a parent task may want to communicate with a child task. Information 
can be sent to and from the child task by using pipes; however, each pipe can send 
information in only one direction. If communication in two directions is desired, two 
pipes must be used. Pipes are similar to files with two critical differences. 

• Files can be reopened many times. Pipes can only be opened once. Once a 
pipe is closed it is gone. 



• 



Files can be reset and repositioned. It is not possible to reposition a pipe. 



Usually the parent task creates a pipe. Each end of the pipe is assigned a file 
descriptor, one for reading and one for writing. When a subtask is created it inherits 
these open file descriptors. The parent task saves one file descriptor, the one which 
is appropriate for its direction of communication. For example, if the parent task 
wants to send information to the child, the parent saves the file descriptor for writing. 
Since the parent will not be using the reading end of the pipe, it should close this 
unused end. The child task must also save the appropriate file descriptor and close 
the file descriptor corresponding to the unused end of the pipe. Neglecting to close 
these unused pipe file descriptors might mean the task could run out of file 
descriptors, since there is a limit on the number of open file descriptors per task. 

Sometimes it is not possible for the child task to know that it should use the pipe's 
file descriptors for reading and writing. For instance, the child task might execute a 
program that writes on standard output. It is possible for the child task to redirect its 
I/O by mapping its pipe descriptors to known file descriptors. Redirection allows a 
file descriptor to capture all the data intended for another descriptor. Tektronix 
Smalltalk Pipe protocol supports this functionality. Once a pipe's file descriptor is 
mapped, it becomes obsolete and should be closed. For example, the child task 
may want to write to the pipe, but the program is designed so write operations go to 
standard output. The write file descriptor of the pipe must be mapped to standard 
output's file descriptor (1), and the pipe's original write file descriptor should be 
closed. The effect of the mapping in this example is for the child task's write 
operations going to standard output to be performed on the write end of the pipe 
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instead. 

Operating System Multi-tasking — Implementation 

In a multi-tasking operating system, programs generally execute by duplicating the 
parent program (task), transforming the duplicate (child) task into the new program. 
Upon termination of the new program, the parent task is signaled; if it suspended 
execution, the parent task resumes. Specific system calls are used to accomplish 
these tasks, kfork call causes the duplication of the parent task. An exec call 
causes the duplicate task (i.e., the child task) to "transform" into a desired 
executable program. An exit call terminates the sending task and causes the 
operating system to send a "dead child signal" to the parent task — this indicates 
that a spawned task has terminated. /Kwait call executed by the parent task, 
besides suspending the parent task until termination of the child task, returns the 
termination status of the child task. Termination status includes information such as 
which signal caused the termination and whether the termination was abnormal. 

For example, suppose you type the command Is at the keyboard. As you know, the 
shell program is waiting to interpret your keystrokes. Here the shell is a parent task. 
If the shell determines that you have typed Is correctly, it forks another shell task — 
a child task. This task then executes an exec call which overlays the child task with 
the Is program, b executes, outputs directory information to the screen, and exits 
normally. The shell task receives the termination status via awflif call and resumes 
its I/O wait for more input from you. 

Discussion 

A subtask is spawned in a Unix-like operating system in three phases: 

• a fork system call, 

• a set-up phase, and 

• the exec system call. 

Most of the code for what takes place in the set-up phase is encapsulated in the 
subtask at the point of instance creation. Between fork and exec the subtask Is 
running Smalltalk, but it is limited. The keyboard and the mouse cannot be used to 
communicate with Smalltalk, so no debugging can take place if the set-up code 
doesn't execute as anticipated. 

In the set-up phase, depending upon which instance creation message selector is 
used and the values of instance variables, several things can take place, such as: 
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• a block of code executes concerning signals and communication; 

• priority of the subtask is set; 

• the environment is changed from the environment that the subtask inherited 
from its parent task. 

Subtask Instance Protocol 

Accessing methods enable the user to set and access the values of instance 
variables. Some instance variables control what happens in the set-up phase, 
others contain information about the termination of the subtask. 

Controlling methods start the subtask, wait for the subtask, and allow the task to be 
interrupted or terminated. 

Testing methods provide information about the subtask, such as whether it is active, 
terminated abnormally, is or is not terminated, and whether the subtask exists. 

Subtask Class Protocol 

Environment variables methods provide information about the current environment 
and allow the environment of the subtask to be modified. The default environment 
for a subtask is the environment of the parent task. 

Instance creation methods provide the encapsulation of data to be used in the set-up 
phase of the subtask. 

Scheduled subtasks and task management methods deal with the subtask management 
system and you will probably not use them directly. 

Relation to the System Call and Pipe Classes 

The system call class is used for the implementation of fork, exec, and wait. It also 
contains protocol for various other operations used by a subtask, including setting 
up signals and priorities. Communication between tasks is currently provided by the 
pipe classes. Access to other communication implementations, such as sockets, is 
available through system calls. 

Management of Subtasks 

A subtask management process is part of Tektronix Smalltalk — it Is implemented 
in the metaclass of Subtask. Unlike the C programming environment where the 
only type of waiting available is complete suspension until the child task terminates, 
the task management system allows two types of waiting, described below. 
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The subtask manager runs continuously, monitoring child tasks. When a task is 
started, it is registered with the task management system. Two lists are used to 
keep track of subtasks — class instance variables scheduledSubtasks and 
unscheduIedSubtasks. 

When a subtask terminates, the manager receives a dead child signal. The 
manager releases a terminated task from its list; if the parent process has been 
suspended, the manager sends a signal for it to resume. 

Waiting 

There are two methods that deal with waiting by the parent task — wait and 
waitWithSmalitalkSuspended. The message wait causes the suspension of only 
the parent process of the subtask. When the subtask ends, the parent is signaled to 
resume. 

The message waitWithSmalitalkSuspended causes the entire Smalltalk task to 
suspend. While Smalltalk is suspended there is no way to interact with the Smalltalk 
task using the keyboard or the mouse. This version of waiting is used for efficiency, 
for example, while a Fortran program doing a lot of calculations is running — like a 
fast Fourier transform. 

Concurrent subtasks may use either form of waiting — their terminations are 
handled appropriately by the subtask manager. 

Snapshots 

If a subtask is running when a snapshot is made, certain things occur. In the 
Smalltalk image that continues to run after the snapshot, the subtask is not affected. 

When you quit, any running subtasks are terminated by the operating system. 
When a Smalltalk image is "brought up" (loaded by the Smalltalk interpreter), the 
subtask management system is installed with empty task lists. If subtasks were 
running when the snapshot was made, they will be marked as #nonexistent. Their 
status can be checked and they can be restarted by application programs. 

Examples 

See the file lusr/liblsmalltalk/fileln/Examples-Subtaskingst (this path correct for UTek 
only) for some examples illustrating how to use Subtask in an application example. 
Read further for an introduction to using Subtask. 
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The Simplest Example 

Here is a very simple example that uses Subtask, 

"Execute a simple binary program with no arguments." 

I task I 

task <- Subtask 

fork: 7usr/bin/pretend' 

then: [ ]. 
task start, 
task wait 

The code above can be executed in a workspace, assuming that the 
7usr/bin/pretend" file exists. It contains the simplest form of subtask instance 
creation, since it has no arguments and does not include a block of code to be 
executed between fork and exec. The default set-up takes place, not a user- 
specified set-up. The task then starts and the parent waits for the subtask to 
terminate. 

Add Some Interest 

Here is a method which executes a program requiring two arguments. It illustrates 
some variations of Subtask protocol and adds error checking code. 

executeUtility: aCommand withArgumentl: argumentStringl 
withArgument2: argumentString2 

"Execute a binary program with two arguments. Set the priority 
of the subtask to the highest possible, and ignore dead child 
signals in the child task. Create an error if the program cannot 
be executed or if the program terminates abnormally." 

I argumentList task envDictionaiy j 
argumentlist «- OrderedCoUection 

with: argumentStringl with: argumentString2. 
task <- Subtask 

fork: aCommand 

withArguments: argumentList 

then: [OS ignorelnterrupf OS deadChildlnterrupt]. 
envDictionary <— Subtask currentEnvironment copy. 
envDictionary at: #PARENT put: 'Smalltalk', 
task environment envDictionary. 
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task enhancedPriority. 
task start isNil 

ifTnie: [self error 'Cannot execute ' , aCommand]. 
Cursor execute 

showWhile: [task wait], 
task abnormalTermination 

ifTrue: [self error 'Abnormal termination from ' , aCommand] 

In the code above, we begin by placing the arguments In an OrderedCoIlection, 
since the instance creation method expects arguments in that form. This example 
uses an instance creation message different from the first example — this one 
allows us to pass arguments to the executable program. 

Set-up Phase 

The block of code after then: is executed only by the child task; it is done in the set- 
up phase. Here the set-up changes the action of an interrupt — the dead child 
interrupt is ignored. The current environment is stored in a temporary variable, 
envDictionary, and the association of #Parent-> 'Smalltalk' is added to it. Then the 
subtask's environment instance variable is set to the value of the temporary 
variable, envDictionary. The subtask is given the highest possible priority. The start 
message causes the execution of the set-up code. 

Start and Finish 

If start returns an error, a notifier is displayed. While the subtask Is executing and 
the parent process waits for the subtask to terminate, the cursor is in the form of a 
star (Cursor execute showWhile:). If the subtask terminates abnormally, an error 
notifier is displayed. 

Related Classes 

In Smalltalk code, the typical reference to the system call class is OS, a global 
variable which is the appropriate system call class for your operating system. You 
might want to refer to these classes in this manual for further information: 

• the system call class for your operating system and its superclasses, 

• the PipeStream hierarchy of classes, and 

• Pipe. 

Pipe is not directly used in the implementation of Subtask, but it is essential to 
complete usage of subtasks. 
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ExternalBinaryData variableByteSubclass: #Tchars 



instanceVariableNames: 
classVariableNames: 



poolDidionaries: 
category: 



'BrkcDatalndex EofcDatalndex IntrcDatalndex 
QuitcDatalndex StartcDatalndex StopcDatalndex 



'OS-Parameters' 



Summary 

Tchars provides accessing protocol fortlie following C structure. 



struct tcfiars { 




char tjntrc; 


/* interrupt */ 


char t_quitc; 


/+ quit */ 


char t_startc; 


/* start output */ 


char t_stopc; 


/♦ stop output ♦/ 


char t_eofc; 


/* end-of-file */ 


char t_brkc; 


/* input delimiter (like nl) */ 



} 

The structure is documented under tty(4) in the manual UTek Command Reference, 
Volume 2. 

Class Variables 

BrkcDatalndex 

EofcDatalndex 

IntrcDatalndex 

QuitcDatalndex 

StartcDatalndex 

StopcDatalndex 

Each C structure class variable holds the offset of a single field in the 
structure. The name of a class variable is constructed from a field name, 
stripped of its prefix, with the string 'Datalndex' appended. For example, 
the class variable BrkcDatalndex holds the offset of the "t brkc" field. 
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Instance Methods 

accessing 



brkc 

Return the value of the structure field named brkc. 

brkc: aCharacter 

Assign the argument, aCharacter, to the structure field named brkc. 

eofc 

Return the value of the structure field named eofc. 

eofc: aCharacter 

Assign the argument, aCharacter, to the structure field named eofc. 

intra 

Return the value of the structure field named intrc. 

intra: aCharacter 

Assign the argument, aCharacter, to the structure field named intrc. 

Intra: iCharacter quite: qCharacter starta: startCharacter 
stopc: stopCharacter eofa: eCharacter brka: bCharacter 
Assign values to all the fields of the structure. 

quite 

Return the value of the structure field named quite. 

quite: aCharacter 

Assign the argument, aCharacter, to the structure field named quite. 

starte 

Return the value of the structure field named starte. 

starte: aCharacter 

Assign the argument, aCharacter, to the structure field named starte. 

stopc 

Return the value of the structure field named stopc. 

stopc: aCharacter 

Assign the argument, aCharacter, to the structure field named stopc. 
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printing 



prIntOn: aStream 

Print the receiver on aStream. 



Class Methods 



class initialization 

initialize 

Assign offset values to the class variables and define the size of the 
structure. 

instance creation 

default 

Return an instance containing the default characters. 

Rationale 

The structure is used in support of the following UTek system call: 
ioctl(2) 

Related Classes 

UTekSystemCall implements the system call listed above. 
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Object subclass: #TextStyle 




instance VariableNames: 


'fontArray lineGrid baseline alignment firstlndent 




restlndent rightlndent tabsArray marginTabs Array 




outputMedium lineGridForLists baselineForLists 




lineGridForMenus baselinePorMenus ' 


class VariableNames: 


" 


pooIDictionaries: 


TextConstants ' 


category: 


'Graphics-Support' 



Summary 

An instance of TextStyle is a grouping of fonts that "lool< nice together" and display 
characteristics used in composing text in these fonts. 

Instance Variables 

alignment <lnteger> 

Indicates the mode for placement from the margins: 
= flush left, 1 = flush right, 2 = centered, 3 = justified. 

baseline <lnteger> 

The amount to be added to the top of a line to find the baseline of the line. 
The baseline is the point from which the ascent of a font should rise. 

baselineForLists <lnteger> 

Copied into baseline while constructing a TextStyle for a list. 

baselinePorMenus <lnteger> 

Copied into baseline while constructing a TextStyle for a menu. 

firstlndent <Integer> 

Amount to inset from the left margin for the first line of a paragraph. Initial 
value for paragraph associated with this TextStyle. 

fontArray <Array> 

A collection of fonts available in this TextStyle. These may be either 
StrikeFonts or VirtualStrikeFonts. The emphasis portion of a Text (the runs 
instance variable) returns a value for indexing into the fontArray. 

llneGrid <lnteger> 

The amount to be added to the top of a line to find the top of the next line. 
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lineGridForLists <Integer> 

Copied into lineGrid while constructing a TextStyle for a list. 

lineGridForMenus <lnteger> 

Copied into lineGrid while constructing a TextStyle for a menu. 

marginlabsArray <Array> 

Each value in the array is a tuple indicating inset values to tab to relative to 
the left and right margin of this paragraph. Allows for inset paragraphs. 

outputMedium <Symbol> 

Currently only ^Display is supported. 

restlndent <lnteger> 

Amount to inset from the left margin for all but the first line of a paragraph. 
Initial value for paragraph associated with this TextStyle. 

rightlndent <lnteger> 

Amount to inset from the right margin for all the lines of the paragraph. 
Initial value for paragraph associated with this TextStyle. 

tabsArray <Array> 

Tab stops. Values are relative to the left margin of the paragraph. 

Pool Dictionaries 

TextConstants 

A dictionary of symbols for non-printing characters, symbols related to text 
composition and text emphasis, and default values for text composition and 
text emphasis. 



Instance Methods 

accessing 



alignment 

Answer the code for the current setting of the alignment. 

alignment: anlnteger 

Set the current setting of the alignment to anlnteger — 0=flush left, 1=flush 
right, 2=centered, 3=justified. 
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baseline 

Answer the distance from the top of the line to the bottom of most of the 
characters (by convention, bottom of A). 

baseline: aninteger 

Set the distance from the top of the line to the bottom of most of the 
characters. 

baseiineForLists 

Answer the baseline for a list composed from this TextStyle. 

baseiineForLists: aninteger 

Set the instance variable baseiineForLists. 

baseiineForMenus 

Answer the baseline for a menu composed from this TextStyle. 

baselineForlVlenus: aninteger 

Set the instance variable baseiineForMenus. 

defaultFont 

Answer the first font in fontArray. 

descent 

Answer the distance from the bottom of most of the characters (by 
convention, bottom of A) to the top of the next line. 

firstlndent 

Answer the horizontal indent of the first line of a paragraph in the style of 
the receiver, 

firstlndent: aninteger 

Set the horizontal indent of the first line of a paragraph in the style of the 
receiver. 

fontArray 

Answer the fontArray of this TextStyle. 

fontArray: aFontArray 

Install aFontArray of fonts; recompute lineGrids and baselines. 

fontAt: index 

Return the StrikeFont at index. Make sure whenever a font is accessed, it 
is coerced into a StrikeFont and registered in the global FontManager. 
Recompute the listStyle and menuStyle based on the font returned. 



Tektronix Smalltalk Reference Manual 199 



TextStyle Graphics-Support 



fontAt: index put: font 

Set the fontArray element at index to font. 

fontFor: fontlndex emphasis: emphasisBlock 

Select and return the index of the first font in fontArray which has the same 
size and family as the font at fontlndex, and where emphasisBlock 
evaluates true. 

fontFor: fontlndex face: face 

Select and return the index of the first font in fontArray which has the same 
size and face as the font at fontlndex. 

fontNamed: aString 

Return the font named aString. If it is not found in fontArray, return the 
basal font for the TextStyle. 

iineGrid 

Answer the relative space between lines of a paragraph in the style of the 
receiver. 

IineGrid: aninteger 

Set the relative space between lines of a paragraph in the style of the 
receiver. 

lineGridForLists 

Answer the relative space between lines of a list in the style of the receiver. 

lineGridForLists: aninteger 

Set the relative space between lines of a list in the style of the receiver. 

lineGridForMenus 

Answer the relative space between lines of a menu in the style of the 
receiver. 

lineGridForMenus: aninteger 

Set the relative space between lines of a menu in the style of the receiver. 

nestingDepth 

Return the number of entries in the marginTabs Array. 

outputMedium 

Answer the outputMedium for this style. 

outputMedium: aSymbol 

Set the outputMedium for this style (currently only #Display is recognized). 
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restindent 

Answer the indent for ail but the first line of a paragraph in the style of the 
receiver. 

restindent: aninteger 

Set the indent for all but the first line of a paragraph in the style of the 
receiver. 

rightlndent 

Answer the right margin indent for the lines of a paragraph in the style of 
the receiver. 

rightlndent: aninteger 

Set the right margin indent for the lines of a paragraph in the style of the 
receiver. 

upperLead: upperLeadlnteger lowerLead: lowerLeadlnteger 

Collect all fonts that are in the largest point size in this TextStyle. Use this 
subset of the fonts to compute the appropriate baseline and line gridding 
including the additional leading amounts specified. 

converting 

asLlstStyle 

Answer a copy of the receiver with lineGrid and baseline set for lists. 

asMenuStyle 

Answer a copy of the receiver with lineGrid and baseline set for menus. 

tabs and margins 

clearlndents 

Reset all the margin (index) settings to 0. 

leftMarginTabAt: marginlndex 

Set the 'nesting' level of left margin indents of the paragraph in the style of 
the receiver to marginlndex. 

nextTabXFrom: anX leftMargin: leftMargin rlghtMargin: rightMargin 

Tab stops are distances from the leftfvlargin. Answer either the first tab 
stop after anX (normalized relative to leftfvlargin) or rightfvlargin, whichever 
is greater. 
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rightMarginTabAt: marginlndex 

Set the 'nesting' level of right margin indents of the paragraph in the style 
of the receiver to marginlndex. 



tabWidth 

Answer the width of standard tab. 



Class Methods 



constants 

default 

Answer the system default text style. 

default: aTextStyle 

Change the system default text style to aTextStyle. 

examples 

allDefaultFontNames 

When you see the star and arrow cursor, select a point (by clicking a 
mouse button) for each font in the DefaultTextStyle. Each font in the 
default text style will be displayed. 

defaultStyleHi 

When you see the star and arrow cursor, select a point by pressing a 
mouse button. The greeting will be displayed there in the system default 
text style. 

instance creation 

fontArray: anArray 

Return a TextStyle constructed from the fonts given in anArray. 



Rationale 



A TextStyle Is used for text composition. It includes a grouping of fonts that "go 
together", often from the same family, and look attractive together interspersed in 
text. In addition to one or more fonts contained in the instance variable fontArray, a 
TextStyle contains information (lineGrid, baseline, and more) computed from the 
largest font in the array. The information aids in the physical layout of multiple lines 
of text. Additionally, you can specify things such as indentation, tabs, and 
alignment. 
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Discussion 

If you are not familiar with some of the terminology In this class, refer to StrlkeFont 
in this manual for an explanation of some of the terms. 

Class Protocol 

Ordinarily, you would not use the instance creation message, fontArray:, to create an 
instance of TextStyle. Instead, use a TextStyleManager text style instance creation 
message or send the message asTextStyle to a StrlkeFont. If you want to create a 
text style for lists or menus in your application, you could use the fontArray: 
message, or use a TextStyleManager message if you want it to be generally 
available. The protocol in the TextStyleManager registers the text style when it is 
created, so that it is accessible to others. Read about the advantages of using the 
TextStyleManager under that class in this manual. 

Constants methods allow you to set the default text style or get a copy of the current 
default text style. 

Instance Protocol 

Accessing methods allow you to set or access the values of the instance variables. 
Additionally, methods install a font or array of fonts, set an element in fontArray to 
the supplied font, or return the index of a font matching a supplied fontlndex' size, 
family, face, or emphasis. One method adjusts the llneGrld and baseUne to 
include supplied "leading" at the top and bottom of the characters. 

Converting methods return a copy of the TextStyle with lineGrid and baseLlne 
adjusted for lists or menus. 

Tabs and margins methods clear all the indents, set the left and right "nesting" level of 
indents, and answer the DefaultTabWidth (from the TextConstants pool 
dictionary). The method nextTabXFrom:leftMargin:rightMargin: answers either 
the first tab stop after a place on the line specified by the user or the right margin, 
whichever is greater. 
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Examples 

The following method is in the TextStyle class examples message category. 

dcfaultStyleHi 

"When you see the star and arrow cursor, select a point by pressing a mouse button. 
The greeting will be displayed there in the system default text style." 

(DisplayText text: 'Hi there !\How are you?' withCRs asText 

textStyle: (TextStyle default)) 
display At: Sensor waitClickButton 

First, the instance creation message textrtextStyle: is sent to DisplayText. The first 
argument must be a Text, so the string is converted to a Text. The message 
withCRs was sent to the string to replace the backslash (\) with a carriage return in 
the string. The second argument is a TextStyle — the one returned by the default 
message is the value at DefaultTextStyle in the TextConstants dictionary. The 
DisplayObject message dIsplayAt: is sent to the instance of DisplayText with the 
argument of the Point created by Sensor waitClickButton. Sensor is a global 
variable, an instance of InputSensor. 

The following method is in the TextStyle class examples message category. 

allDefaultFontNames 

"When you see the star and arrow cursor, select a point (by clicking a mouse button) for 
each font in the DefaultTextStyle. Each font in the default text style will be displayed." 

(TextConstants aL- ^DefaultTextStyle) fontArray do: 

[: strikeFont | 

(DisplayText text: strikeFont name asText textStyle: strikeFont asTextStyle) 

display At: Sensor waitClickButton] 

This method takes defaultStyleHi one step farther, and makes use of additional 
TextStyle methods. TextConstants at: #DefaultTcxtStyle returns the same result as 
TextStyle default, used in the preceding example. The instance of TextStyle is sent 
the message fontArray, and the returned array of StrikeFonts is enumerated with a 
block similar to the code in the first example. Instead of the greeting, the argument 
to text: is the string returned by sending the message name to the StrikeFont. The 
argument to textStyle: is the TextStyle returned when the message asTextStyle is 
sent to the StrikeFont. When this example is executed in the standard image 
(assuming that you have not changed the default text style), 16 font names are 
displayed using a separate TextStyle for each one. One point of this example is 
that text must be converted to a displayable object, in this case a DisplayText, in 
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order to display it. In fact, all text that you see in Smalltalk is converted to a 
displayable object, but that is handled for you and you aren't required to do the 
converting in everyday use. Unless you want to deal with the Forms in the glyphs 
instance variable of a StrlkeFont, the only way to see a StrlkeFont is to make it a 
TextStyle and display some text using the TextStyle. 

Related Classes 

DisplayText 

Paragraph 

StrlkeFont 

StrlkeFontManager 

String 

Text 

TextStyleManager 

VIrtualStrikeFont 
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Dictionary variableSubclass: #TextStyleManager 

instance VariableNames: 

classVariableNames: 'MenuDependents TextStyleMenu 

TextStyleNames ' 
pooIDictionaries: 
category: 'Graphics-Support' 



Summary 

This class is the central repository of all TextStyles. TextStyleManager maps 
TextStyle names (Strings) to TextStyles. 

Class Variables 

MenuDependents <OrderedCollection> 

The list of MenuDependents is kept so that whenever the default text style 
changes, all cached menus are flushed. To add a menu to the list, send 
the message addMenuDependents: to the global StyleManager. Each 
element of MenuDependents is itself a collection of three elements: 

• The symbol name of a Smalltalk class or other entry in the system 
dictionary. 

• The symbol #class or #instance. 

• The symbol name of a unary message selector. 

TextStyleMenu <PopUpMenu> 

A menu of available TextStyle selections. 

TextStyleNames <Dictionary> 

A dictionary of TextStyle names and associated TextStyles. 



instance Metiiods 

accessing 



at: aString put: aTextStyle 

Install aTextStyle named aString. 
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removeAssociation: anAssociation ifAbsent: aBlock 

Remove the key and value association, anAssociation, from the receiver. 
Cause all MenuDependents to be flushed. Answer anAssociation. 

removeKey: aString ifAbsent: aBlock 

Remove the TextStyle named aStrIng else answer aBlock value. 

default text style 

changeDefaultTextStyle 

Present a menu of TextStyles. If one is selected, change the default 
TextStyle. 

ChangeDefaultTextStyle: aTextStyle 

Change the default TextStyle to aTextStyle. 

mem initialization 

InitializeMenus 

Initialize all of the system menus. New classes cacheing menus or other 
dependencies upon TextStyle should be added to the list of 
MenuDependents by sending the message addMenuDependents: to 
TextStyleManager. 



selecting 

fromUser 

Present a menu of TextStyles. Answer with the selected TextStyle. If no 
TextStyle is available or selected, return nil. 

fromUser: aBlock 

Present a menu of TextStyles. If one is selected, evaluate aBlock with the 
selected TextStyle and return the selected TextStyle. Return nil if no 
TextStyle is selected. 

text style instance creation 

styleName: aString baseNames: anArray 

Create and install a TextStyle named aString with fonts specified by 
anArray of base String names. Load or synthesize the fonts if necessary. 
Set the leading to zero. Answer the TextStyle. 

Each base name in anArray represents a set of eight fonts (Basal, Bold, 
Italic, Boldltalic, Basal Underlined. Bold Underlined, Italic Underlined, and 
Boldltalic Underlined). The font order within the new TextStyle is best 
explained by the following example: 
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StyleManager styleName: Tellucida Sans-Serif 10/12' baseNames: 
#('PellucidaSans-SeriflO"PellucidaSans-Serifl2') 

The code above generates a TextStyle with font order: 



'PellucidaSans-Serif 1 0' 
'PellucidaSans-Serif 1 0B' 
'PellucidaSans-Serif 1 01' 
'PellucidaSans-Serif 1 0X' 

'PellucidaSans-Serif 1 2' 
'PellucidaSans-Serif 1 2B' 
'PellucidaSans-Serif 1 21' 
'PellucidaSans-Serif 1 2X' 

'PellucidaSans-Serif 1 0U' 
'PellucidaSans-Serif 1 0BU' 
'PellucidaSans-Serif 1 0IL)' 
'PellucidaSans-Serif 1 0XU' 

'PellucidaSans-Serif 1 2U' 
'PellucidaSans-Serif 1 2BU' 
'PellucidaSans-Serif 12IU' 
'PellucidaSans-Serif 12XU' 



(Basal) 
(Bold) 
(Italic) 
(Bold Italic) 

(Basal) 
(Bold) 
(Italic) 
(Bold Italic) 

(Underlined) 
(Bold Underlined) 
(Italic Underlined) 
(Bold Italic Underlined) 

(Underlined) 
(Bold Underlined) 
(Italic Underlined) 
(Bold Italic Underlined) 



StyleName: aString baseNames: anArray lead: leadlnteger 

Similar to styleNameibaseNames:, but divide the leading equally between 
upper and lower leading (odd pixel on top). 

StyleName: aString baseNames: anArray upperLead: upperLeadlnteger 
lowerLead: lowerLead Integer 
Similar to styleNameibaseNames:, but set the upper and lower leading. 

StyleName: aString fontNames: anArray 

Create and install a TextStyle named aString with fonts specified by 
anArray of explicit String names. Set the leading to zero. Answer the 
TextStyle. 

StyleName: aString fontNames: anArray lead: leadlnteger 

Similar to styleNameifontNames:, but divide the leading equally between 
upper and lower leading (odd pixel on top). 
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styleName: aString fontNames: anArray upperLead: upperLeadlnteger 
lowerLead: lowerLead Integer 
Similar to styieName:fontNames:, but set the upper and lower leading. 



Class Methods 



class initialization 

flushMenus 

Set tlie TextStyleMenu to nil. 

initialize 

Install a new style manager if necessary. Build a new MenuDependents 
list. 

initializeStyleManager 

Install standard text styles into the StyleManager. 

examples 

bigHi 

When you see the star and arrow cursor, move the cursor where you want 
it and press a mouse button. The greeting will be displayed in large Italic 
letters. 

instance creation 

new: aninteger 

Flush the style menu because the new instance will probably be installed 
as StyleManager. 

menu initialization 

addMenuDependents: aCollection 

Extend the list of MenuDependents by the list contained within aCollection. 
Each element of aCollection should itself be a collection of three elements: 

• The symbol name of a Smalltalk class or other entry in the system 
dictionary. 

• The symbol #class or #instance. 

• The symbol name of a unary message selector. 
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When an instance of the receiver (typically the Smalltalk global 
StyleManager) receives the message initializeMenus, for each menu 
dependent the unary message is sent either to the class (#class) or to all 
instances of the class (#instance). 

menuDependents 

Answer the list of MenuDependents. 

Rationale 

This class maps names to TextStyles and provides a user-friendly interface to 
TextStyles, enabling the user to change the default text style, select from a menu of 
TextStyles, and add TextStyles to the menu. It keeps a list of TextStyles — once 
it is registered with the TextStyleManager, a TextStyle can be used anywhere in 
Smalltalk. When a TextStyle is removed from the menu, it will still be available to 
anything in Smalltalk that uses that TextStyle. 

The TextStyleManager insures that when the default text style is changed all menu 
dependents are updated to the new default. 

Discussion 

Class Protocol 

Ordinarily there is only one TextStyleManager, referred to by the global variable 
StyleManager. You are not prevented from creating an instance of 
TextStyleManager which is not the global manager. This implementation assumes, 
however, that a new TextStyleManager will be installed as StyleManager, so when 
the message new: is sent to the class, the TextStyleMenu is set to nil. Besides 
setting the TextStyleMenu to nil, class initialization includes a method to initialize 
this class. 

Menu initialization methods allow you to add menu dependents or access 
MenuDependents. The message addMenuDependents: should be sent to the 
global StyleManager whenever you add a menu to the system, so that if the default 
text style is changed the menu(s) you added will be updated. 

Instance Protocol 

Accessing methods enable you to add a TextStyle to the manager, or remove a style 
from the manager by specifying either the String name of the TextStyle or the 
Association of a String name and a TextStyle. Either adding or removing a 
TextStyle causes the TextStyleMenu to be set to nil. 
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Default text style methods enable you to set the default text style by selecting one 
from the menu or specifying one. 

Menu initialization contains one method to initialize all of the menus listed in 
MenuDependents. This message is sent by another method and is one you 
probably won't use. 

Selecting contains two methods, fromUser and fromUser:, which return a TextStyle 
you select from a menu and evaluate a block with the selected TextStyle, 
respectively. 

Text style instance creation includes a number of methods to create a TextStyle by 
providing a String name for the style (any name you prefer) and an Array of base 
String names (actual names of font families — found in the directory answered by 
OS fontDirectory fullName.). An alternative to base names is to provide an Array of 
fonts (either StrikeFonts or VirtualStrikeFonts). You also have the option of 
specifying "leading" to be divided equally at the top and bottom or separate "leading" 
at the top and bottom of a "line" of characters. Using the messages in this message 
category, TextStyles can be arbitrarily named, however, the convention is to use a 
name that reflects the grouping of fonts. The difference between the "baseName" 
and "fontName" methods is that the former load a group of eight fonts in a default 
order for each base name, the latter only load the fonts explicitly named in the array 
and in the order they are listed in the array. 

The messages in text style instance creation are the preferred way to create text 
styles, instead of the TextStyle class instance creation message fontArray:. The 
messages here will register the new style with the manager. 

Examples 

The following method is in the TextStyleManager class examples message 
category. 

bigHi 

"When you see the star and arrow cursor, move the cursor where you want it and press 
a mouse button. The greeting will be displayed in large Italic letters." 

I lines styleName | 

styleName <- 'BigStyle'. 

StyleManager styleName: styleName fontNames: #('PellucidaSans-Serif36r). 

lines <r- Hi there!\How are you?' withCRs. 

(DisplayText text: (lines asText) textStyle: (StyleManager at: styleName)) 
display At Sensor waitClickfiutton. 

StyleManager removeKey: styleName if Absent: [ ]. 
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First, a text style instance creation message is sent to the global StyleManager to 
create a TextStyle. On style menus Its name is 'BigStyle'. 'BigStyle' has one font, 
Pellucida Sans-Serif 361, in its fontArray, If a TextStyle is not registered with the 
manager, it cannot be referred to by name and cannot be accessed throughout 
Smalltalk. 

Next, a String is created with two lines of characters — note the use of a backslash 
to indicate the carriage return and the message withCRs. The simplest way to 
display the string using a TextStyle is to make it a DisplayText. The instance 
creation message takes a Text and a TextStyle as arguments, then the 
DisplayText is displayed where you press a mouse button. Finally, 'BigStyle' is 
removed from the global StyleManager. 

Related Classes 

StrlkeFont 
StrlkeFontManager 
TextStyle 
VlrtuaiStrikeFont 
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ExternalBinaryuata variableByteSubclass: #Timeval 

instance VariableNames: 

classVariableNames: 'SecDatalndex UsecDatalndex 

pooIDictionaries: 

category: 'OS-Parameters' 



Summary 

Timeval provides creation and accessing protocol for the following C structure. 

struct timeval ( 

long tv_sec; /+ seconds */ 

long tv_usec; /* microseconds */ 
} 

The structure is documented under gettimeofday(2) in the manual UTek Command 
Reference, Volume 2. 

Class Variables 

SecDatalndex 
UsecDatalndex 

Each C structure class variable holds the offset of a single field in the 
structure. The name of a class variable is constructed from a field name, 
stripped of its prefix, with the string 'Datalndex' appended. For example, 
the class variable SecDatalndex holds the offset of the "tv sec" field. 



Instance Methods 

accessing 
sec 



Return the value of the structure field named sec. 

sec: anint 

Assign the argument, anint, to the structure field named sec. 
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sec: anint usee: anotherint 

Assign values to all the fields of the structure. 

usee 

Return the value of the structure field named usee. 

usee: anInt 

Assign the argument, anint, to the structure field named usee. 

converting 

asTime 

Return an instance of Time equivalent to the receiver. 



printing 



printOn: aStream 

Print the receiver on aStream. 



Class Methods 



class initialization 

initialize 

Assign offset values to the class variables and define the size of the 
structure. 

instance creation 

sec: anInt usee: anotherint 

Return an instance with the values of the fields assigned. 

Rationale 

The timeval C structure is used in support of these UTek system calls: 

adjtime(2) 

cfsettimeofdayd) 

gettimeofday(2) 

selectil) 

settimeofday(2) 

utimes(2) 

Related Classes 

UTekSystemCall implements the following system calls which use the timeval 
structure: 
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geUimeofday(2) 

select(2) 

utimes(2). 

The other system calls which use this structure have not been implemented 
because they are only available to the superuser (root). 
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ExternalBinaryData variableByteSubclass: #Time2one 

instanceVariableNames: 

classVariableNames: 'DsttimeDatalndex MinuteswestDatalndex ' 

poolDictionaries: 

category: 'OS-Parameters' 



Summary 

Timezone provides creation and accessing protocol for the following C structure. 

struct timezone { 

int tz_minuteswest; /* minutes west of Greenwich */ 

int tz_dsttime; /* type of dst correction ♦/ 

} 

The structure is documented under gettimeofday(2) in the manual UTek Command 
Reference, Volume 2. 

Class Variables 

DsttimeDatalndex 
MinuteswestDatalndex 

Each C structure class variable holds the offset of a single field in the 
structure. The name of a class variable is constructed from a field name, 
stripped of its prefix, with the string 'Datalndex' appended. For example, 
the class variable DsttimeDatalndex holds the offset of the "tz_dsttime" 
field. 

Instance Methods 

accessing 

dsttime 

Return the value of the structure field named dsttime. 
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dsttime: anint 

Assign the argument, anInt , to the structure field named dsttime. 

minuteswest 

Return the value of the structure field named minuteswest. 

minuteswest: anInt 

Assign the argument, anInt , to the structure field named minuteswest. 

minuteswest: anInt dsttime: anotherint 

Assign values to all the fields of the structure. 



printing 



prlntOn: aStream 

Print the receiver on aStream. 



Class Methods 



class initialization 

initialize 

Assign offset values to the class variables and define the size of the 
structure. 

instance creation 

minuteswest: anInt dsttime: anotherint 

Return an instance with the values of the fields assigned. 

Rationale 

The structure is used in support of the following UTek system calls: 

cfsettimeofday(2) 

gettimeofdayd) 

settimeofdayU) 

Related Classes 

UTekSystemCall implements the following system call which uses the timezone 
structure: 

gettimeofdayd). 

The other system calls which use this structure have not been implemented 
because they are only available to the superuser (root). 
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AbstractFileStatus variableWordSubclass: #UniflexFileStatus 

instance VariableNames: 

class VariableNames: 

poolDictionaries: 

category: 'OS-Interface' 



Summary 

An instance of this class is a buffer which contains information about a file. The 
following questions are answered by file status information. 

• Is the file a directory? 

• When was the file last modified? 

• What is the file descriptor? 

The file status class is usually not used in isolation, but in conjunction with the 
system call class or with FlleStream. As a result of the following code, three things 
happen — an instance of UniflexFileStatus is created, the buffer is filled, and the 
instance is returned: 

OS status: aFileDescriptor 

In the code above, UniflexSystemCall is referred to by the global variable OS. See 
the 4400 Series Assembly Language manual. Section 4 System Calls, "status" for 
details about the contents of the buffer. 



Instance Methods 

accessing 



buffer 

The receiver is the buffer which holds the file status information. 

fileSize 

Answer the file size in bytes. 
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isDirectory 

Answer whether the file represented by the receiver is a directory. 

isReadable 

Answer true if the file represented by the receiver is readable. 

isWritable 

Answer true if the file represented by the receiver is writable. 

lastModified 

Answer the time of the last modification to the file. 

longDescription 

Answer a String that contains a description of the receiver which looks like 
a line from a dir command. 

comparing 

= aFileStatus 

Answer true if the fdn and device number are the same. 

hash 

Hash is reimplemented because = is implemented. 



Class Methods 

instance creation 
new 



Answer a new instance of the receiver. 



Rationale 



This class is a concrete subclass of AbstractFileStatus and uses the protocol 
framework established there. UniflexFileStatus serves as an interface to the 
operating system structure which holds file status information. 
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AimSystemCall variableSubclass: 

instanceVariableNames: 
classVariableNames: 
poolDictionaries: 
category: 


#UniflexSystemCall 
'OS-Interface' 



Summary 

This is the concrete class used to inteiiace to the operating system on the Tek 4404, 
4405 or 4406. It defines instance creation and portable operations implementation 
for the UniFLEX operating system used by these workstations. 

Instance Methods 

execution 

systemlnvokeQuietly 

Make a system call. Return success or failure of the system call, or nil if 
the primitive fails. 

portable subtask operations 

terminatedSubtaskExitCode 

Answer the low byte of the status returned from the wait system call. This 
portion represents the value of the argument supplied by the exit system 
call causing termination. The high order bit of the portion indicates whether 
the terminated task has made a core dump. The receiver must be an 
instance representing a wait system call, which has been executed. 

terminatedSubtaskExitlnterrupt 

Answer the high byte of the status returned from the wait system call. This 
portion represents the value of the signal causing termination. The 
receiver must be an instance representing a wait system call, which has 
been executed. 
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terminatedSubtaskID 

Answer the ID returned from the wait system call. The receiver must be an 
instance representing a wait system call, which has been executed. 



Class Methods 



class initialization 

initialize 

Initialize the error message array used by UniflexSystemCall objects. 

environment variables 

argCount 

Return the number of arguments used to invoke Smalltalk. 

originalEnvlronment 

Return the environment used to invoke Smalltalk. 

file names 

backupFileName: aFileName 

Answer a string which is a backup file name for the file aFileName. 

isBackupFileName: aFileName 

Does aFileName correspond to a name that is usually a backup file name? 

general inquiries 

abnormalTerminatlonCode 

Answer the code for abnormal task termination. 

asTlme: osSeconds 

Convert the operating system's notion of time to a Time. The operating 
system has corrected for time zone and daylight savings time. Add in the 
total seconds from Jan. 1, 1901 (the start of Smalltalk time) up to Jan. 1, 
1980 (the start of Uniflex time). 

brokenPipelnterrupt 

Answer the interrupt number for the broken pipes interrupt. 
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deadChlldlnterrupt 

Answer the interrupt number for the dead child interrupt. 

defaultlnterruptCode 

Answer an operating system representation of the default interrupt action. 

fileBufferSize 

Return the preferred size of a buffer used for reading files. 

fileStatusClass 

Answer the class whose instances hold the file status returned by system 
calls that are instances of the receiver. 

font Directory 

Return the directory which contains font files. Each file contains a font in 
external font format. 

getMachineName 

Return the type of machine Smalltalk is running on. 

IgnorelnterruptCode 

Answer an operating system representation of the ignore interrupt action. 

IsValld 

Does this class represent the operating system running on this machine? 
(This method should return true only if the underlying operating system is 
Uniflex.) 

maxFileNameSIze 

Answer the maximum number of characters permissible for file names. 

maxOpenFiles 

Answer the maximum number of simultaneously open files. 

nonBlockingWait 

Answer true if the wait instance creation method returns a non-blocking 
call, false otherwise. Uniflex has a blocking wait call. 

prioritylnterval 

Answer the interval of valid priorities in ascending order for this operating 
system. Maximum values range from to 25, zero being the highest and 
25 being the lowest; however, this range is restricted for most users. 
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retumKeyCode 

Answer the Smalltalk character value which should be assigned when the 
return key is pressed. The Uniflex operating system uses the CR 
convention. 

smalltalklnitializationDirectory 

Return the directory which contains initialization files. Each file contains 
Smalltalk readable data used during class initialization. 

terminatelnterrupt 

Answer the interrupt number for the terminate interrupt. This interrupt can 
be caught. 

terminateUnconditionallylnterrupt 

Answer the interrupt number for the terminate unconditionally interrupt. 
This interrupt cannot be caught. 

validPriorlty: aPriority 

Answer the validity of this priority for this task. 

portable directory operations 

changeDlrectory: aString 

Change directory to the specified directory. 

createDlrectory: aString 

Make aString, a full path name, be a new directory. 

currentDirectoryName 

Answer the complete path name of the current working directory, 

nextFlleName: directoryStream 

Answer the next file name in directoryStream. Advance the directory 
stream beyond that name. Answer nil if none. 

Directories are formatted into 16-byte entries, the last 14 of which contain 
the characters of the file names. Short names use one entry with zero fill if 
required. Long names use multiple consecutive entries all of which are 
marked in the high-order bit of their first character position. A zero byte 
(ignoring marks) is guaranteed. 

removeDlrectory: aString 

Remove the directory named aString. The directory must be empty (i.e., 
contain only . and ..). 
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portable file operations 

create: aString 

Create a new file named aString. Answer a writeOnly fileDescriptor for the 
file. 

duplicateFd: fileDescriptor 

Return a new file descriptor that references the same open file as 
fileDescriptor. 

duplicateFd: oldFlleDescriptor with: newFileDescriptor 

Cause newFileDescriptor to reference the same open file as 
oldFlleDescriptor. If newFileDescriptor currently references an open file, 
that file is first closed. 

existlngName: fileName 

Answer true if a file or directory exists by the name fileName, a String. 

freeFileDescrlptors 

Answer the number of available file descriptors. 

newPIpe 

Return an instance of Pipe. 

open: aString 

Open the file named aString. Answer a readWrite fileDescriptor for the file. 

openForRead: aString 

Open the file named aString. Answer a readOnly fileDescriptor for the file. 

openForWrlte: aString 

Open the file named aString. Answer a writeOnly fileDescriptor for the file. 

read: fileDescriptor Into: aStringOrByteArray 

Fill aStringOrByteArray with data from the file referred to by fileDescriptor. 
Answer the number of bytes read. Answer zero if at end. 

read: fileDescriptor Into: aStringOrByteArray size: count 

Fill aStringOrByteArray with, at most, count data elements from the file 
referred to by fileDescriptor. Return the number of bytes read, or zero if at 
end. 
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rename: aFileName as: newFileName 

Rename the file named aFileName to have the name newFileName. 
Create an error if aFileName does not exist; but not if newFileName exists. 

seek: aFileDescriptor to: aFilePos'rtion 

Position the file represented by aFileDescriptor to aFilePosition bytes from 
its beginning. 

shorten: fileDescriptor 

Shorten a file to its current position. 

size: fd 

Return the count of available bytes from the file or pipe known by the file 
descriptor fd. 

status: fd 

Return a UniflexFileStatus for the file known by the file descriptor fd. 

statusName: fileName 

Answer a UniflexFileStatus for the file referred to by fileName, a String. 

validFiieDescriptor: fileDescriptor 

Answer true if an open file with the specified file descriptor exists. 

write: fileDescriptor from: aStringOrByteArray size: byteCount 

Write byteCount bytes of data from aStringOrByteArray to the file referred 
to by fileDescriptor. 

portable subtask operations 

brokenPipesProcessWith: aBlock 

Answer a process that monitors broken pipes. ABlock is executed after the 
receipt of each broken pipe signal. 

executeUtillty: aCommand withArguments: anOrderedCollection 

Execute a binary program and return the entire results generated by the 
program as a string. No mechanism for input to the program is provided. 
Notify an error if the program cannot be executed or if the program 
terminates abnormally. 

executeUtilltyWIthErrorWIapping: aCommand 
withArguments: anOrderedCollection 

Execute a binary program and return an array of two strings. The first 
string contains the entire normal output generated by the program. The 
second string contains any error message output from the program. No 
mechanism for input to the executable program is provided. Notify an error 
if the program cannot be executed or if the program terminates abnormally. 
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forkShell 

Fork an operating system shell with history. Type 'exit' to the shell to 
return to Smalltalk. 

sendlnterrupt: anInterruptID to: aTaskID 

Send an 'interrupt' to a task by specifiying an interruptID and a tasklD. 
Return true if the operation was successful, false otherwise. First check to 
see if aTaskID is a valid task ID. 

setlnterrupt: anInterruptID to: aSemaphoreOrParameter 

Override the default action for an 'interrupt' by connecting it to a 
semaphore or some system specific parameter. If specified, the 
semaphore is posted on interrupt. After the interrupt is received, the 
interrupt must be reconnected or it will return to its default action. The 
exception to this is the DeadChildlnterrupt, number 26. 

setTaskPrlorlty: priority 

Set the priority of this task to a value which should be included in this class' 
priority interval. 

shell 

Fork an operating system shell with history. Type 'exit' to the shell to 
return to Smalltalk. 

startSubtask: executeCall withBIock: childBlock 

Start the subtask by spawning a child task. Then, the child task only 
evaluates the childBlock, and executes the executeCall to transform the 
child task into another program. If the executeCall fails, terminate the child 
task. The child task will inherit the priority of the Smalltalk task. Answer 
the spawned child task ID, nil if none. 

terminate: aTaskID 

Using an interrupt, attempt to terminate the task associated with the 
specified ID. This termination is requested in a manner which can be 
intercepted. 

termlnatedSubtasksProcessWIth: aBlock 

Answer a process that monitors spawned child tasks. ABlock is executed 
after the termination of each child task. The dead child signal is 
automatically reset by the operating system. 



termlnateUncondltionally: aTaskID 
Terminate this task unconditionally. 
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system-environment variables 

invocatlonArgCountAddress 

Get the address of the argument count used in this Smalltalk. 



system-files 



chacc: fileName mode: permlnteger 

Check the accessibility of the file fileName. 

chdir: directoryName 
Change directory. 

chown: fileName to: ownerlD 

Change owner of a fileName to ownerlD. 

chprm: fileName to: permissions 
Change permissions for a file. 

close: fileDescriptor 
Close a file. 

controlPty: fileDescriptor command: cmd mode: modeByte 

Control, via the master end, the slave side of a pty. The fileDescriptor is a 
master mode pseudo-terminal file descriptor. The state of the channel is 
returned in DO. The argument cmd is a subfunction and modeByte is the 
argument to the subfunction. 

create: fileName mode: modeBits 
Create a new file. 

createRy 

Create a pseudo terminal master/slave device pair, known as a channel. 
The file descriptor for slave access is returned in DO and the file descriptor 
for master access is returned in AO. Once the channel has been created, 
additional slave accesses may be created using UniflexSystemCall 
open:mode:. UniflexSystemCall ofstat:buffer: may be used to get 
Information about the status of master and slave sides. 

crtsd: newName mode: mode addr: addr 

To create a directory, mode should be 8r04077 and addr should be 0. 

deface: permissions 

Set the default permissions. 
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dup: fileDescriptor 

Duplicate the file descriptor; open the file again. 

dups: fileDescriptor with: specif iedDescriptor 

Duplicate the file descriptor, specifying the file descriptor of the duplicated 
open file. 

fcnti: fileDescriptor function: controlFunction 

Change or interrogate the behavior of a file. The state of the modifiable 
behaviors is returned in DO. 



controlFunction Result 

Get the state (1 = noblock, 2 = block). 

2 Answer file descriptor of last file which sent INPUT 
READY signal, -1 if none. 

3 Subsequent reads on this descriptor do not block. 
Error ENOINPUT is returned if no data and signal 
INPUT READY sent when data becomes available. 

4 Subsequent reads do block. 

filtime: fileName to: time 

Set last modified time of file. 

link: fileName to: linkName 
Link a file to a link name. 

ofstat: fileDescriptor buffer: buff 
Get the status of an open file. 

open: fileName mode: modeBits 
Open a file. 

status: fileName buffer: buf 

Read the status of file fileName into the buffer buf. Buf should be 
aWordArray of size 1 1 . 

unlink: fileName 
Unlink a file. 
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system-information 

time: tbuff 

Get the system time. Tbuff should be a WordArray of size 5. 

ttlme: tbuff 

Get the current task's time, Tbuff should be a WordArray of size 8. 

system-input output 

read: fileDescriptor buffer: buff nbytes: numberOf Bytes 

Perform a read operation with the appropriately sized buffer. 

seek: fileDescriptor offset: position whence: start 
Change the position in the file. 

truncate: fileDescriptor 

Truncate the file at the current position. 

ttyget: fileDescriptor buffer: ttybuff 

Get the tty description of the specified open file. Ttybuff should be a 
WordArray of size 3. 

ttynumber 

Get the number of the calling task's terminal. 

ttyset:flleDescriptor buffer: ttybuff 

Set the tty information as described in ttyget. 

update 

Update the contents of system disks. 

write: fileDescriptor buffer: buff nbytes: numberOfBytes 
Write numberOfBytes from buff to a file. 

system-resources 

Irec: fileDescriptor howmany: count 

Make an entry in system's locked record table. 

rump: resourceName operation: resourceOperation 

Create, destroy, enqueue or dequeue a named resource. Used to provide 
a mechanism for controlling access to physical resources. The 
resourceName must be no larger than 15 characters. ResourceOperation 
should be a Smalllnteger , 1 representing enqueue, 2 representing 
dequeue, 3 representing create, and 4 representing destroy. 
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urec: fileDescriptor 
Unlock a file record. 

system-subtasks 

alarm: seconds 

Set alarm to go off in seconds. Return previous value of seconds in DO. 

cpint: interrupt to: aSemaphoreOrAddress 

Set an interrupt from the operating system to signal a semaphore or tell the 
operating system upon interrupt to branch to an address. It may be used 
to restore the old interrupt address also. The old address (or semaphore) 
is returned in DO. 

crPIpe 

Create a pipe. 

exec: fileName with: argLlst 

Execute a binary file specified by fileName. FileName is a character string. 
ArgList is an OrderedCollection of character strings. The task ID is 
returned in DO. 

execute: program wIthArguments: argCollection 
with Environment: environmentDictionary 

Answer an instantiated instance of the exec system call with arguments 
and environment variables in the proper format. The exec call has not 
been invoked yet. 

execve: pathName wIthArgs: argList wIthEnv: envList 

Execute a binary file specified by pathName. PathName is a character 
string. ArgList is an OrderedCollection of character strings. EnvList is an 
OrderedCollection of environmental strings in the following format: 
environment name = the corresponding environment value string (no 
spaces around equal). For example, 'HOME=/public'. 

If the executable program is /bin/shell or /bin/script, it v/ill create a default 
environment if it is passed a null environment. The task ID is returned in 
DO. 

exit: exitParam 

Answer an instance of the exit system call. It has not been invoked yet. 

fork 

Answer an instance of the appropriate fork system call. It has not been 
invoked yet. 
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forkProcess 

Create a new task. The new task receives a copy of the entire address 
space. Return the task's ID in DO. 

getid 

Get the running task's ID. 

getuld 

Get the actual user ID and the effective user ID. 

setpr: priority 

Set the priority. 

setuld: userlD 

Set the actual user ID and the effective user ID. 

spint: taskNumber an: interrupt 

Send a task, specified by taskNumber (ID), an interrupt. 

term: terminatingStatus 

Terminate a task with an error indicating status (zero = no error). 

vfork 

Create a new child task. The new task does not receive a copy of the 
entire address space, instead the parent and child processes share 
memory. Return the child task ID in DO. 

wait 

Wait for a child or a program interrupt. DO returns taskID and AO returns 
termination status. 

yieldCPU 

Yield the CPU to tasks of equal priority. 

Rationale 

UniflexSystemCall is the primary interface between Smalltalk and the operating 
system on Tektronix 4400 series workstations. Smalltalk requires operating system 
services, the very least of which is being able to interact with the UniFLEX operating 
system file system. Additionally, there are many other functions/programs 
accessible via the operating system that should be usable from within Smalltalk. 

Related Classes 

AbstractSystemCall 

AimSystemCall 

Subtask 
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AbstractFileStatus subclass: 

instanceVariableNames: 
classVariableNames: 
poolDictionaries: 
category: 


#UTekFiIeStatus 
'buffer ' 

'OS-Interface' 



Summary 

An instance of this class contains a buffer holding information about a file. 
Information may be things like 

• Is the file a directory?, 

• Last time the file was modified, and 

• File descriptor. 

The file status class is not usually used in isolation, but in conjunction with the 
system call class or with FileStream. As a result of the following code, three things 
happen — an Instance of UTekFileStatus is created, the buffer is filled, and the 
instance is returned: 

OS status: aPileDescriptor. 
In the code above, UTekSystemCall is referred to by the global variable OS. 

Instance Variables 

buffer <Stat> 

The structure which contains the file information. 



Instance Methods 

accessing 
buffer 



Answer the buffer which holds the file status information. 

flleSize 

Answer the file size In bytes. 
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isDirectory 

Answer true if the receiver is a directory. 

isReadable 

Answer true if the file represented by the receiver is readable. 

isWritable 

Answer true if the file represented by the receiver is writable. 

lastModifled 

Answer the time of the last modification to the file. 

comparing 

= aFileStatus 

The combination of device name (major and minor numbers) and i-number 
serves to uniquely name a particular file. 

hash 

Hash is reimplemented because = is implemented. 

Class Methods 

instance creation 

new 

Answer a new instance of the receiver containing an instance of the C 
structure class Stat. 

Rationale 

This class is a concrete subclass of AbstractFileStatus and uses the protocol 
framework established there. UTekFlleStatus serves as an interface to the 
operating system C structure which holds file status information. 
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AimSystemCall variableSubclass: #UTekSystemCall 

instanceVariableNames: 

classVariableNames: 'SystemCallKeywords ' 

poolDictionaries: 

category: 'OS-Interface' 



Summary 

UTekSystemCall is the class used to interface to the operating system on Tektronix 
UTek workstations. It is normally accessed through the global variable OS. In 
practice, a specific instance creation message is sent to the UTekSystemCall in 
order to create a data object with the proper format, then the message invoke is 
sent to the new system call object to actually cause the execution of the system call, 
with success or failure being returned. A similar message, value, causes a notifier 
upon system call failure, and returns the system call return value upon success. 

This class is responsible for implementing all the protocol defined in its abstract 
superclasses, AimSystemCall and AbstractSystemCall. 

Instance Variables 

Inherited Instance Variables 

AOIn <PointerArray> 

This inherited variable contains the argument(s), if any, to the system call. 

DOIn <lnteger> 

This inherited variable contains the value of the opcode symbol in the 
SystemCallKeywords dictionary. 

DOOut <lnteger> 

This inherited variable contains the value returned from the system call. 

D10ut <lnteger> 

This inherited variable sometimes contains supplementary return value 
information. 

errno <lnteger> 

This inherited variable contains an error number upon system call failure. 
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operation <SymboI> 

This inherited variable contains the symbolic name for the system call. 

operationType <Symbol> 

This inherited variable contains a message selector identifying the action to 
take upon receiving the #invoke or #value message. 

All other inherited instance variables are ignored. 

Class Variables 

SystemCallKeywords <Dictionary> 

Symbols corresponding to the system call names are associated with 
system call indices. 

Inherited Class Variables 

ErrorMessages <Array> 

This inherited variable contains strings associated with error numbers. 

Pool Dictionaries 

Inherited Pool Dictionaries 

ErrorConstants 

This inherited pool contains symbolic names for error numbers. 

OSConstants 

This inherited pool contains symbolic names for commonly used numeric 
constants. 

instance Methods 

initialize-release 



operation: opcode 

Set up a system call with no arguments. Set the operation to the proper 
code. 

operation: opcode with: argO 
operation: opcode with: argO with: arg1 
operation: opcode with: argO with: argi with: arg2 
operation: opcode with: argO with: arg1 with: arg2 with: arg3 
operation: opcode with: argO with: arg1 with: arg2 with: argS with: arg4 
operation: opcode with: argO with: arg1 with: arg2 with: arg3 with: arg4 

with: arg5 

Set up the arguments for a system call. Set the operation to the proper 

code. 
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accessing 



at: index put: argument 

Place a system call argument in the desired stack position. 



constants 



systemCallKeywordFor: syscalilndex 

Answer a String from the SystemCallKeywords dictionary that corresponds 
to syscalilndex. 

systemCallValueFor: aSymbol 

Answer a value from the SystemCallKeywords dictionary that corresponds 
to aSymbol. If aSymbol is not found, notify the user that it is a bad key. 



errors 



error: errorLabel 

Report a system call error with a verbose explanation. 

errorString 

Return a string that is associated with the present error code. If there is no 
string available, return a String representation of the error code. 

issueError 

Issue a notifier with a string that identifies the failed UTekSystemCall. 



execution 



returnDI 

Cause the system call primitive to return a value in DIOut. 

signallnvoke 

Perform signal/semaphore mapping. 

systemlnvokeQuietly 

Make a system call. Return success or failure of the system call, or nil if 
the primitive fails. 

value 

Evaluate the system call represented by the receiver. Answer the return 
value for a successful call; create an error notifier otherwise. 

valuelfError: aBlock 

Evaluate the system call represented by the receiver. Evaluate aBlock if 
the system call resulted in an error. Return the result of the system call 
otherwise. 
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waitinvoke 

Make a wait call. Return success or failure of that system call. Notify if the 
primitive failed. This method is necessary because wait and wait3 have an 
assembly code interface that differs from all other system calls. 

operation type 

signalOperation 

The desired operation involves a signal/semaphore link. 

waitOperation 

The desired operation involves a wait or wait3 system call. 

portable subtask operations 

termlnatedSubtaskExitCode 

Return a portion of the status returned from the wait system call. This 
portion represents the value of the argument supplied by the exit system 
call causing termination. The high order bit of the portion indicates whether 
the terminated task has made a core dump. The receiver must be an 
instance representing a wait system call, which has been executed. 

terminatedSubtaskExitlnterrupt 

Return a portion of the status returned from the wait system call. This 
portion represents the value of the signal causing termination. The 
receiver must be an instance representing a wait system call, which has 
been executed. 



printing 



printOn: function 

Print a representation of the system call similar to that used in the UTek 
manual. 



Class Methods 



class initialization 

firstTime 

Initialize a brand new image under Smalltalk. This method assumes that 
Disk and SourceFiles are initialized. 

initialize 

Read in the constants and messages needed for UTek System Calls. 
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initiallzeErrorMessages 

Load the ErrorConstants pool. Load the class array ErrorMessages using 
the UTek "msghip" utility. 

constants 

constant: aString 

Return the value associated with aString. 

keysAtValue: val 

Return a set of symbols that are associated with the value val. 

systemCallKeywordFor: syscalllndex 

Return a Symbol from the SystemCallKeywords dictionary that 
corresponds to syscalllndex. 

systemCallValueFor: aSymbol 

Return a value from the SystemCallKeywords dictionary that corresponds 
to aSymbol. If aSymbol is not found, notify the user that it is a bad key. 

environment variables 

argCount 

Return the number of arguments used to invoke Smalltalk. 

originalEnvironment 

Return the environment used to invoke Smalltalk. 



filenames 

backupFileName: aPileName 

Answer a string which is a backup file name for the file aPileName. 

isBackupFileName: aPileName 

Does aPileName correspond to a name that is usually a backup file name? 

general inquiries 

abnormalTerminationCode 

Return the code for abnormal task termination. 
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asTime: osSeconds 

Convert the operating system's notion of time to a Time. Add in the total 
seconds from Jan. 1,1901 (the start of Smalltalk time) up to Jan. 1 , 1 970 
(the start of UTek time). Add a correction value for time zone and daylight 
savings time. 

brokenPipelnterrupt 

Return the interrupt number for the broken pipes interrupt. 

deadChiidlnterrupt 

Return the interrupt number for the dead child interrupt. 

defaultlnterruptCode 

Answer the code that will restore the default interrupt action. 

fileBufferSize 

Return the preferred size of a buffer used for reading files. 

fileStatusClass 

Answer the class of objects returned from system calls that return file 
status. 

fontDirectory 

Return the directory which contains font files. Each file contains a font in 
external font format. 

getMachineName 

Return the type of machine Smalltalk is running on. 

ignorelnterruptCode 

Answer the code that will cause interrupts to be ignored. 

isValid 

Does this class represent the operating system running on this machine? 
(This method should return true only if the underlying operating system is 
UTek.) 

maxFlleNameSize 

Answer the maximum number of characters permissible for file names. 

maxOpenFiles 

Answer the maximum number of simultaneously open files. 
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nonBlockingWalt 

Does the UTekSystemCall #wait method retum immediately rather than 
blocking? 

prioritylnterval 

Return the interval of valid priorities in order of descending priority for this 
task and effective user. 

return KeyCode 

Answer Smalltalk character value which should be assigned when the 
return key is pressed. UTek returns a linefeed. 

smalltalklnitializationDirectory 

Return the directory which contains initialization files. Each file contains 
Smalltalk readable data used during class initialization. 

terminatelnterrupt 

Return the interrupt number for the terminate interrupt. This interrupt may 
be caught. 

terminateUnconditionallylnterrupt 

Return the interrupt number for an unconditional interrupt. This interrupt 
may not be caught. 

validPriority: aPriority 

Is aPriority a valid priority for this task and user? 

portable directory operations 

changeDirectory: aDirectoryName 

Change the current directory to the specified directory. 

createDirectory: directoryName 

Create a new directory with the name directoryName. 

currentDirectoryName 

Return a String with the name of the current working directory. 

nextFileName: directoryStream 

Return the next existing file name in directoryStream. Advance the 
directory stream beyond that name. Answer nil if none. UTek directories 
have the following variant structure: 
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struct direct { 

ujong djno; /+inode number for the file*/ 

short d_recien; /*length of this record, dword padded*/ 

short d_namlen; /*length of the file name*/ 

char d_name[d_namlen+l]}; /*file name itself*/ 

To tell if a directory entry is unused, one must look at the previous entry to 
see if d_reclen is bigger than would be expected. This is not terribly easy 
to do with a Stream on variant records, so we take the coward's way out: 
get the name of the file, see if it exists, and either return the validated 
name, or go get the next one. 

removeDirectory: directoryName 

Remove the directory named directoryName. 

portable file operations 

create: fileName 

Create a new file named fileName. Answer a writeOnly fileDescriptor for 
the file. 

duplicateFd: fileDescriptor 

Return a new file descriptor that references the same open file as 
fileDescriptor. 

duplicateFd: oldFilelD with: newFilelD 

Duplicate the existing file descriptor oldFilelD, to the specified new file 
descriptor newFilelD. If newFilelD already existed, it is first closed. The 
old and new descriptors share an open file. The new file descriptor is 
returned. 

existingName: fileName 

Answer true if a file or directory exists by the name fileName. 

freeFileDescriptors 

Answer the number of available file descriptors. 

newPipe 

Return an instance of Pipe. 
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open: fileName 

Open the file named fileName. Answer a readWrite fileDescriptor for the 
file. 

openForRead: fileName 

Open the file named fileName. Answer a readonly fileDescriptor for the 
file. 

openForWrite: fileName 

Open the file named fileName. Answer a writeOnly fileDescriptor for the 
file. 

read: fileDescriptor Into: aStringOrByteArray 

Fill aStringOrByteArray with data from the open file known by 
fileDescriptor. Return the number of bytes read, or zero if at end. 

read: fileDescriptor into: aStringOrByteArray size: count 

Fill aStringOrByteArray with, at most, count data elements from the file 
referred to by fileDescriptor. Return the number of bytes read, or zero if at 
end. 

rename: fileName as: newFileName 

Rename the file named fileName to have the name newFileName. Create 
an error if fileName does not exist, but not if newFileName exists. 

seel<: aFileDescriptor to: aFilePosition 

Position the file known by aFileDescriptor to aFilePosition bytes from its 
beginning. Return the resulting position. 

shorten: fileDescriptor 

Shorten a file to its current position. 

status: fd 

Return a FileStatus for the file known by the file descriptor fd. 

statusName: fileName 

Return a FileStatus for the file named fileName. 

vaiidFiie Descriptor: fd 

Answer true if an open file with the specified file descriptor exists. 

write: fileDescriptor from: aStringOrByteArray size: byteCount 

Write byteCount bytes of data from aStringOrByteArray to the file known 
by fileDescriptor. Return the actual number of bytes written. 
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portable subtask operations 

brokenPipesProcessWith: aBlock 

Return a process that monitors broken pipes. ABlock is executed after the 
receipt of each broken pipe signal. 

defaultlnterrupt: anInterruptID 

Set the specified interrupt to its default action. The previous action is 
returned. 

execute: program withArguments: argCoIlection withEnvironment: envDictionary 
Answer an instance of the exec system call that has not yet been invoked. 

forkShell 

Set up the display and signal environment for terminal emulation, and turn 
it over to a forked shell Subtask. Block on the Subtask until it terminates, 
then restore the display and signal environment for Smalltalk. 

ignorelnterrupt: interruptID 

Set the specified interrupt to be ignored. The previous action is returned. 

sendlnterrupt: interruptID to: taskID 

Send the interrupt known by interruptID to the task known by tasklD. 
Return true if the operation was successful, false otherwise. First check to 
see if taskID is a valid task ID. 

setlnterrupt: interruptID to: aSemaphoreOrAddress 

Override the default action for the interrupt known by interruptID by 
connecting it to aSemaphore or the address of a subroutine. The 
semaphore is posted on interrupt. The old semaphore (or address) is 
returned. 

setTaskPriority: priority 

Set the priority of Smalltalk to the value priority, 

shell 

Set up the display and signal environment for terminal emulation. Either 
suspend Smalltalk (for shells that support it) or fork a new shell. Restore 
the display and signal environment for Smalltalk upon resumption. 

startSubtask: execCall withBlock: childBlock 

Fork a copy of Smalltalk. In the child copy, execute childBlock and invoke 
execCall, which must be an instantiated 'exec' system call. If execCall 
returns, there is an error: terminate the child task. Meanwhile, the parent 
task returns the child task ID. 
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terminate: taskID 

Using an interrupt, attempt to terminate \he task known by tasklD. This 
termination Is requested in a manner which can be intercepted. 

termlnatedSubtasksProcessWith: aBlock 

Return a Process that moniters spawned child tasks. ABlock is executed 
after the termination of each child task. The dead child signal is 
automatically reset by the operating system. 

terminateUncondltlonally: aTaskID 
Terminate this task unconditionally. 

wait 

Answer an instance of the wait system call that has not yet been invoked. 



system-files 



access: pathName mode: modeBits 

Access returns the value in DO if the file pathName is accessible for 
reading, writing, or executing according to the modeBits. 

chdir: pathName 

Change the current working directory to pathName. 

chmod: pathName mode: modeBits 

Change the file pathName to have a mode described by modeBits. 

close: filelD 

Delete the file referenced by the file descriptor, filelD, from the reference 
table. If this is the last reference to the underlying object, it will be 
deactivated. 

dup2: oldFilelD newfd: newFilelD 

Duplicate the existing file descriptor oldFilelD, to the specified new file 
descriptor newFilelD. If newFilelD already existed, it is first closed. The 
old and new descriptors share an open file. The new file descriptor is 
returned in DO. 

dup: OldFilelD 

Duplicate the existing file descriptor oldFilelD, by creating a new file 
descriptor. The old and new descriptors share an open file. The new file 
descriptor is returned in DO. 

fchmod: filelD mode: modeBits 

Change the file denoted by filelD to have a mode described by modeBits. 
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fcnti: filelD cmd: command ID arg: commandArg 

Fcntl is used to control various aspects of the open file known by the 
descriptor filelD, depending on the Integer arguments, commandID and 
commandArg. An Integer value is returned in DO. The following table 
describes the various actions of fcntl (X means don't care or undefined). 



commandID commandArg DOOut 



Action 



F_DUPFD 


an fd 




newfd 


return a new fd >= 
commandArg 


F GETFD 


X 




flag 


return close-on-exec flag 


F_SETFD 


Oor1 




X 


set close-on-exec flag to 
commandArg 


F GETFL 


X 




status flags 


return current status flags 


F SETFL 


status 


flags 


X 


set status flags 


F GETOWN 


X 




pg negated 


return process group 


F SETOWN 


pg nee 


gated 


X 


set process group to pg 


F SETOWN 


pid 




X 


set process group to that 
of process pid 



Status flags are defined as a bitOr: of the following values: 

FNDELAY FilelD is in non-blocking mode. If a read or write would 

block, the call fails with the error code EWOULDBLOCK. 
FAPPEND Writes to filelD are appended to the end of the file. 
FASYNC Send SIGIO to the process group when I/O is possible. 

flock: filelD operation: operationID 

Flock controls advisory locks that cooperating processes may associate 
with files. Locks can be applied either exclusively or shared, and may be 
set non-blocking. OperationID is a set of bit flags used to determine the 
type of lock that will be applied to the open file descriptor filelD. 

fstat: filelD buf: statStructure 

Fstat returns information in statStructure about the open file known by the 
descriptor filelD. 

link: oldPathName path2: newPathName 

Create a new directory entry newPathName for the file oldPathName. Both 
paths must be on the same file system. 
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Istat: pathName buf: statStructure 

Lstat returns information in statStructure about the file or symbolic link 
pathName. 

mkdir: directoryName mode: modeBits 

Mkdir creates a new directory directoryName with the mode being 
modeBits combined with the current mode mask. 

open: pathName flags: options mode: modeBits 

Open the file pathName under the control of options. If the file does not 
exist and options specify creation, set the new file's mode to modeBits, in 
combination with the current mode mask. A file descriptor by which the 
open file is known is returned in DO. 

readlink: symbolicLinkPathName buf: linkByteData bufsiz: linkSize 
Readlink returns in linkByteData the contents of the symbolic link 
symbolicLinkPathName. LinkByteData must be at least linkSize. The 
number of characters read is returned in DO. 

rename: oldFiieName to: newFileName 

Rename causes the file oldFiieName to be known as newFileName. 

rmdir: directoryPathName 

Rmdir removes the directory known as directoryPathName. 

Stat: pathName buf: statStructure 

Stat returns information in statStructure about the file pathName. 

symlink: oldPathName path2: newPathName 

Symlink creates a symbolic link to oldPathName in a file named 
newPathName. 

umask: newUmask 

Umask sets the file creation mode mask for Smalltalk to newUmask. The 
previous mode mask is returned in DO. 

unlink: pathName 

Unlink removes the reference to pathName from its directory. The file will 
not go away if there are other links to it or it is open in any process. 

utimes: pathName tvp: timevalStructurePair 

The last access and last modified times, respectively, for the file pathName 
are returned in timevalStructurePair. 
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system-information 

getdtablesize 

Getdtablesize returns the number of files that may be open at any given 
time in DO, which is the size of the descriptor table. This value exists in a 
constant and is obtained quickly via the expression: 

UTekSystemCall constant: 'NOFILE'. 

getegid 

Getegid returns the actual group ID of the user running Smalltalk in DO and 
the effective group ID of the user running Smalltalk in D1. This may be 
different than the actual group ID of the user running Smalltalk if Smalltalk 
has the set-group-ID bit set. 

geteuld 

Geteuid returns the actual user ID of the user running Smalltalk in DO and 
the effective user ID of the user running Smalltalk in D1. This may be 
different than the actual user ID of the user running Smalltalk if Smalltalk 
has the set-user-ID bit set. 

getgid 

Getgid returns the actual group ID of the user running Smalltalk in DO and 
the effective group ID of the user running Smalltalk in D1. This may be 
different than the actual group ID of the user running Smalltalk if Smalltalk 
has the set-group-ID bit set. 

gethostname: hostName namelen: hostNameSize 

Gethostname places this machine's name in hostName, which must 
contain room for at least hostNameSize characters. 

getitimer: timerType value: timerStructure 

Getitimer returns in timerStructure information for one of three interval 
timers, determined by timerType. 

getpagesize 

Getpagesize returns the number of bytes in a Memory Management Unit 
page in DO. 

getrlimit: resourcelD rip: rlimitStructure 

Return in rlimitStructure the resource limits imposed on the Smalltalk 
process and its children. 

gettlmeofday: timevalStructure tzp: timezoneStructure 

Return the system's notion of the current Greenwich Mean Time and the 
local time zone in timevalStructure and timezoneStructure. 
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getuid 

Getuid returns the actual user ID of the user running Smalltalk in DO and 
the effective user ID of the user running Smalltalk in D1, This may be 
different than the actual user ID of the user running Smalltalk if Smalltalk 
has the set-user-ID bit set. 

mstat: memoryType addr: startAddress len: length vec: processString 
Return in processString information describing the process clusters of a 
particular memoryType beginning at startAddress and continuing for length 
bytes. 

profil: tallyByteArray bufsiz: tallySize offset: pcStart scale: granularity 
Profil allows execution time profiling by examining the user program 
counter each clock interval. Offset is subtracted from the PC, multiplied by 
granularity, and tallied in tallyByteArray if the result is within tallySize. 

setitimer: timerType value: timerStructure ovalue: oldTimerStructure 

Setitimer sets one of three interval timers, determined by timerType, to the 
value specified in timerStructure. The previous value for that timer is 
returned in oldTimerStructure. 

setregid: realGroupID egid: effectiveGroupID 

Setregid sets the real and effective group IDs of Smalltalk to realGroupID 
and effectiveGroupID, respectively. Only root may change the real group 
ID, others may only set the effective group ID to the real group ID. 

setreuid: realUserlD euld: effectiveUserlD 

Setreuid sets the real and effective user IDs of Smalltalk to realUserlD and 
effectiveUserlD, respectively. Only root may change the real user ID, 
others may only set the effective user ID to the real user ID. 

setrlimit: resourcelD rip: rlimitStructure 

Setrlimit changes the resource limits for Smalltalk and its children to the 
limits described in rlimitStructure. 

uname: utsnameStructure 

Uname returns in utsnameStructure information identifying the current 
operating system. 

system-input output 

fsync: filelD 

Fsync causes an open file descriptor filelD, to have a disk representation 
consistent with its memory representation. 
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ftruncate: filelD length: truncatedSize 

Ftruncate causes a file that is open for writing known by the descriptor 
filelD to be reduced to a given size, if it is currently larger than that size. 
Truncated data are lost. 

iocti: filelD request: commandID argp: argByteArray 

Set or get the operating characteristics of the open device file known by the 
descriptor filelD according to commandID and argByteArray. CommandID 
is an Integer that both identifies the request and describes argByteArray: 



union commandID { 


int command; 


struct field { 


short 


in:1 ; 


short 


out:1; 


short 


unused:?; 


short 


Ien:7; 


short 


request}} 



/*set if argByteArray gets input*/ 
/*set if argByteArray gets output*/ 

/♦length of argByteArray, max 128*/ 
/*ioctl request code*/ 



(The fields in commandID are built properly by the "OS constant: 
requestString" expression.) locti requests are device dependent. The 
following table links devices, available requests, and UTek manual pages 
from Command Reference, Volume 2, Section 4: 



Device 




Manual 


Requests 


ethernet 


ARP, 


ILAN, 


LNA, LO, 


Manipulate network interfaces. 




NETWORKING 




parallel port 


HC 






Set/clear CRM/RCSM modes. 


tape 


MTIO 






Control operation of raw cartridge 
tape device. 


RS-232 port 


RSA 






Control operation of RS-232 port. 


terminals 


TTY 






Control operation of console, tty 
port, and pseudo-ttys. 



Ternriinals and RS-232 ports are the devices most often sent ioctI requests. 
The following requests are available for controlling these devices: 
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Request Action 



TIOCSETD. TIOCGETD Set/get line discipline: old, new, or network. 

TIOCSPGRP, TIOCGPGRP Set/get process group for current process. 

TIOCMODS, TIOCMODG Set/get RS-232 port control lines. 

TIOCSETP, TIOCGETP Set/get parameters as in stty/gtty. 

TIOCSETC, TIOCGETC Set/get special characters. 

TIOCFLUSH Flush buffers. 

TIOCSTI Simulate terminal input, 

TIOCPKT Set/clear pseudo-tty packet. 

. . . and many, many more. See TTY(4) for details. 

Iseek: filelD offset: bytes whence: offsetType 

Lseek moves the file pointer associated with the descriptor filelD by bytes 
positions, and returns the new value of the file pointer in DO. OffsetType 
specifies absolute, incremental, or extending movement, 

read: filelD but: byteData nbytes: byteDataSize 
■ Read data from the file known by the descriptor filelD into byteData, which 
must be of at least byteDataSize. The number of bytes actually read is 
returned in DO. 

readv: filelD lev: bufferArray lovcnt: bufferArraySize 

Read data from the file known by the descriptor filelD into the buffers 
referenced in bufferArray, which must be of at least bufferArraySize. 
Readv may not be used on raw devices or across a network. The number 
of bytes actually read is returned in DO, 

select: fileCount readfd: readFiles writefd: writeFiles exceptfd: pendingFiles 
timeout: timevalStructure 

Select examines the open files corresponding to the bit masks readFiles, 
writeFiles, and pendingFiles to see if they are ready for reading, writing, or 
have exceptional conditions pending, respectively. At most, fileCount 
descriptors are examined, ReadFiles, writeFiles, and pendingFiles then 
return a bit mask corresponding to those descriptors that were found ready, 
with the total number of ready descriptors returned in DO. If 
iinievalStructure is zero, select blocks until all descriptors are ready, 
othen^ise timevalStructure indicates how long to wait for ready descriptors. 

sync 

Sync causes all in-core information that should be on disk to be written out. 
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truncate: pathName length: truncatedSize 

Truncate causes the file pathName to be reduced to a given size, if it is 
currently larger than that size. Truncated data are lost. 

write: filelD buf : byteData nbytes: byteDataSize 

Write writes byteDataSize bytes from the buffer byteData into the open file 
known by descriptor filelD. The number of bytes actually written is returned 
in DO. 

writev: filelD lov: bufferArray lovcnt: bufferArraySize 

Writev writes the number of buffers specified by bufferArraySize into the 
open file known by descriptor filelD These buffers are described 
iovecStructures contained in bufferArray. The number of bytes actually 
written is returned in DO. 

system-sockets 

accept: socketID addr: sockaddrStructure addrlen: sockaddrSize 

Accept a connection on a socket by creating a new socket. The new 
socket has the same properties as the socket denoted by socketID. Thi? 
operation follows blocking/nonblocking protocol. The length argument (a 
4-byte quantity) initially contains a pointer to the size of the socket address 
buffer, and returns the new size of the buffer. The descriptor of the new 
socket is returned in DO. 

bind: socketID name: sockaddrStructure namelen: sockaddrSize 

Bind a name to a socket. After use, this socket must be deleted by the 
user with the unlink call. The socket, denoted by socketID, is bound to a 
name described by sockaddrStructure of length sockaddrSize. 

connect: socketID name: sockaddrStructure namelen: sockaddrSize 

Either specify the peer to which datagrams are sent or initiate a connection 
on another socket, socketID. The length of the socket name is specified by 
sockaddrSize. 

getpeername: socketID name: sockaddrStructure namelen: sockaddrSize 
Getpeername returns the name of the peer connected to socket socketID 
in sockaddrStructure. SockaddrSize is a pointer to the actual size of 
sockaddrStructure, which returns the actual size of the returned 
sockaddrStructure. 
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getsockname: socketID name: sockaddrStructure namelen: sockaddrSize 
Return in sockaddrStructure the name of the socket socketID. 
SockaddrStructure must be of size sockaddrSize, and the size of the 
returned name is returned in sockaddrSize. 

getsockopt: socketID level: optionType optname: optionID optval: optionString 
optlen: optionSize 

Return the options of optionType and optionID associated with the socket 
socketID in optionString. OptionSize is the length allocated for 
OptionString, and is modified to indicate the actual size of the returned 
OptionString. 

listen: socketID backlog: maximumQueueLength 

Establish a backlog queue of maximumQueueLength for the socket 
socketID. 

recv: socketID buf: byteData len: byteDataSize flags: options 

Recv returns a message from the connected socket socketID in byteData, 
which must be of at least byteDataSize. The number of bytes actually 
received is returned in DO. 

recvfrom: socketID buf: byteData len: byteDataSize flags: options 
from: sockaddrStructure fromlen: sockaddrSize 

Recvfrom returns a message from the socket socketID in byteData, which 
must be of at least byteDataSize. If sockaddrStructure is zero, no source 
address is received, otherwise sockaddrStructure returns the source 
address. SockaddrStructure must be at least sockaddrSize bytes. The 
number of bytes actually received is returned in DO. 

recvmsg: socketID msg: msghdrStructure flags: options 

Recvmsg returns a message from the socket socketID as directed by the 
msghdrStructure, which locates the sockaddr structure, output buffers, and 
access rights to be used. The number of bytes actually received is 
returned in DO. 

send: socketID msg: byteData len: byteDataSize flags: options 

Send transmits the message byteData of length byteDataSize to the 
connected socket socketID, as confi-olled by options. The number of 
characters actually sent is returned in DO. 

sendmsg: socketID msg: msghdrStructure flags: options 

Sendmsg transmits the message described by msghdrStructure to the 
socket socketID, as controlled by options. The number of characters 
actually sent is returned in DO. 
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sendto: socketID msg: byteData len: byteDataSize flags: options 
to: sockaddrStructure tolen: sockaddrSize 

Senc'to transmits the message byteData of length byteDataSize to the 
socket socketID described by sockaddrStructure, as controlled by options. 
The number of characters actually sent is returned in DO. 

setsockopt: socketID level: optionType optname: optionID optval: optionString 
optlen: optionSize 

Set the options of optionType and optionID associated with the socket 
socketID to the values described in optionString, which is of size 
OptionSize. 

shutdown: socketID how: endID 

Shutdown causes all or part of a full-duplex connection with socket 
socketID to be closed. The part disconnected is described by end ID. 

socket: addressType type: socketType protocol: protocol 

Socket creates a socket of socketType using the address format 
addressType and the given protocol. A new socket descriptor is returned 
in DO. 

socketpair: domain type: socketType protocol: protocol sv: socketlDs 

Socketpair creates a pair of connected sockets of socketType in the given 
domain using the given protocol. A pair of new socket descriptors is 
returned in socketlDs. 

system-subtasks 

execve: pathName argv: arguments envp: environmentVariables 

Transform Smalltalk into a new UTek process. The file specified by 
pathName is either an executable object file, or a data file for an 
interpreter. Arguments is an array of null-terminated strings, the first of 
which must be the name of the executable program, pathName. 
EnvironmentVariables is an array of null-terminated strings, each of which 
is in the form "namesvaiue". There is no return from this system call. 

exit: status 

Terminate Smalltalk with the given status. All descriptors are closed, the 
parent process may be notified of the status throught the wait system call, 
and existing child processes have their parent ID changed to 1. There is 
no return from this system call. 
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fork 

Fork causes a copy of the current Smalltalk process to be created. The 
pareiit finds the new task ID in DO and the value in D1 . The new task 
finds the parent task ID in DO and the value 1 in D1 . 

getgroups: maxEntries gidset: groupSet 

Getgroups stores the group access list for the Smalltalk process in the 
groupSet array, which contains at least maxEntries. 

getpgrp: processID 

Getpgrp returns the process group of the process processID, which, if zero, 
specifies this Smalltalk. The group ID is returned in DO. 

getpid 

Return the process ID of Smalltalk in DO. 

getppid 

Return the process ID of Smalltalk in DO. Return the process ID of 
Smalltalk's parent in D1. 

getprlorlty: priority Type who: identifier 

Return the scheduling priority of a process, process group, or user as 
determined by priorityType. Identifier is either a process ID, process group 
ID, or user ID, as appropriate. The priority is returned in DO. 

getrusage: whoFlag rusage: rusageStructure 

Return in rusageStructure information about resource usage of Smalltalk or 
its terminated children, as indicated by whoFlag. 

kill: processID sig: signallD 

Send the process known by processID the signal signallD. 

kill: processID sig: signallD arg: signalArgument 

Send the process known by processID the signal signallD with the 
argument signalArgument. 

kilipg: processGroupID sig: signallD 

Send the process group known by processGroupID the signal signallD. 

pipe 

Pipe creates an interprocess communication channel. The read end of the 
pipe is known by the descriptor in DO, while the write end of the pipe is 
known by the descriptor in D1 . 
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ptrace: actionCode pid: processID addr: processAddr data: processData 
Ptrace allows interactive control of a child process processID. The 
actionCode argument controls interpretation of the processAddr and 
processData arguments. 

setpgrp: processID pgrp: groupID 

Setpgrp sets the process group of the process processID to grouplD. 

setprlority: priority Type wfio: identifier prio: newPriority 

Set the scheduling priority of a process, process group or user as 
determined by priority Type to the value newPriority. Identifier is either a 
process ID, process group ID, or user ID, as appropriate. 

sigblock: blockedSignalsMask 

Sigblock causes signals specified in blockedSignalsMask to be added to 
the set of signals currently blocked. A mask representing the signals 
previously blocked is returned in DO. 

sigpause: blockedSignalsMask 

Sigpausc causes signals specified in blockedSignalsMask to become the 
set of signals currently blocked. It then waits for a signal to arrive, finally 
restoring the previous blocked signal mask. 

sigsetmask: blockedSignalsMask 

Sigmask causes signals specified in blockedSignalsMask to become the 
set of signals currently blocked. A mask representing the signals 
previously blocked is returned in DO. 

walt3: waitStructure options: blocking rusage: rusageStructure 

Waits checks the status of child processes, optionally without suspending, 
as controlled by blocking. Upon return from wait, waitStructure contains 
both the exit code and the termination status of the child that died, unless 
waitStructure was set to zero before the call, in which case no status is 
returned. If rusageStructure is non-zero, information concerning the 
resource usage of terminated children is returned in rusageStructure. The 
process ID of the stopped or terminated child process is returned in DO. 

wait: waitStructure 

Wait suspends Smalltalk until it receives a signal or one of its children dies. 
Upon return from wait, waitStructure contains both the exit code and the 
termination status of the child that died, unless waitStructure was set to 
zero before the call, in which case no status is returned. The process ID of 
the stopped or terminated child process is returned in DO. 
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Rationale 

UTekSystemCall is the primary interface between Smalltalk and the operating 
system. Smalltalk requires operating system services, the very least of which is 
being able to read operating system files. Additionally, there are many other 
functions/programs accessible via the operating system that should be usable from 
within Smalltalk. 

Background 

Essential operating system services are defined in protocol found in either 
AbstractSystemCall or AlmSystemCall. Those two classes establish the pattern 
of protocol to be implemented or overridden by methods in the subclasses for 
specific operating systems. Examples of essential services are open: and 
cIoseFlle: to open and close files in the operating system; read:into: and 
write:from:slze to read and write files; changeDirectory: to move to a different 
directory; and caiis to fork and execve needed for subtasking. In addition to 
implementing or overriding protocol in its two immediate superclasses, 
UTekSystemCall contains specific protocol needed for the UTek operating system 
interface and UTeK-specific services such as network access. 

System Calls 

Often the intended outcome of a system call is the side effect of the call (e.g., writing 
to a file) rather than what the call returns. In the UTek operating system, system 
calls are generally used by functions that directly invoke UTek system operations. 
In Smalltalk, however, the UTek system Of^erations are invoked via Smalltalk 
primitives. There are three types of system interface operations: 

• display operations (primitive method displaylnvoke), 

• semaphore or signal operations (primitive method signallnvoke), and 

• system and wait operations (primitive method systemlnvokeQuletly). 

When one of the three types of calls is made, the communication between Smalltalk 
and the operating system is accomplished through one of the three primitives — the 
second and third types of system interface operations are implemented in 
UTekSystemCall. These are system calls which are found in Section 2 of the 
manual UTek Command Reference. Display operations are implemented in 
AlmSystemCall. 

You should read the intro{2) section in Utek Command Reference for additional 
information about system call error messages and terminology. 
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Discussion 

Most system calls will be accomplished by methods found in the message 
categories with "portable" in their name, for example, portable directory operations. 
Under those categories are the message selectors that will fulfill the most common 
system call requirements. 

UTekSystemCall also provides non-portable methods under "system-" categories 
for every system call in Section 2 of the UTek Command Reference except 

• calls that could destroy the running Smalltalk process/task (e.g., memory 
management calls), and 

• system calls which are only accessible to root. 

Before using these non-portable calls, the documentation of the call in Section 2 of 
UTek Convnand Reference should be reviewed. 

Naming Convention 

The naming convention for the message selectors under "system-" categories is as 
follows. The first keyword is the name of the UTek system call. The first argument 
is the first argument expected by the system call. Succeeding keywords and 
arguments name and supply, respectively, the remaining arguments to the system 
call. For example, the specification newfd ■=• dup2 (oldfd,newfd) {dup2(2)\n 
UTek Command Reference) is implemented as this UTekSystemCall class message 
selector: 

dup2: oldFilelD newfd: newFilelD 

dup2 is the system call name. 
oldFilelD is the first argument, 
newfd: names the second argument, newFilelD. 

Class Protocol — Portable and System- Methods 

Wherever possible, the "portable" operations should be used to ensure operating 
system independence. In images released for the UTek operating system, the 
global variable OS is set to UTekSystemCall. OS should be used in code (instead 
of the name of your system call class) to insure the portability of the code. 
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The class message categories beginning with "portable" should be checked first 
when you need to make a system call. Those categories will be the ones you use 
most frequently. The "portable" methods often send messages found under 
"system-" categories, but most of the "system-" methods can be thought of as 
private. 

For example, suppose you want to duplicate a file descriptor. The po, table file 
operations category contains the method duplicateFd:. This is the message that 
you should use. It works by calling dup:, which is found under system-files. The 
message dup: is sent to the global variable OS. If the system call fails, a notifier is 
displayed; otherwise, dup: returns the new file descriptor. 

There is no way to tell from looking at the dup: meliiod that the preferred message 
for your purpose is duplicateFd: — just follow the rule of thumb to look under 
"portable" first for the message you need. If you use a non-portable message 
selector, it will work but may not be as "user-friendly" as the portable one — dup: 
doesn't display the notifier that duplicateFd: displays when appropriate. In 
addition, moving your code to other Tektronix Smalltalk images will be much easier 
if you use the "portable" operations. 

Portable directory operations allow you to manipulate directories, such as changing 
the current directory, enumerating the files in a directory, and creating or removing a 
directory. 

Portable file operations allow you to perform common operations on files, such as 
creating, checking for existence, various file descriptor operations, renaming, 
opening, reading, positioning, creating pipes, writing, and obtaining file status 
information. 

Portable subtask operations allow you to create new processes, send interrupts to 
processes, and change the response to interrupts. 

The protocol is arranged with all the direct-map system calls together under 
"system-". "Direct-map" methods are those described under the preceding section 
called "Naming Convention". If no portable message exists for what you need to do, 
for example, socket operations or ioctl, the direct system call message should be 
used. 

System-files methods are system calls that deal with testing, opening, closing, status, 
names, and descriptors of files. 

System-information methods are system calls that return information from the system, 
such as user and group ID, host name, and timers. They are primarily concerned 
with returning information, as opposed to taking some action. 
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System- input output methods are system calls that read, write, seek, and deal with 
input and output in other ways. 

System-sockets methods are system calls that are concerned with creating, 
connecting, receiving, and sending data on sockets. 

System-subtasks methods are system calls that are concerned with UTek processes 
— creating, interrupting (signaling), and process ID. 

Class Protocol — Other Message Categories 

Class initialization methods initialize the class variables and pool dictionaries, if 
necessary. The flrstTlme method initializes the Smalltalk image for a specific 
operating system. 

Certain operating system information is available (without making a system call) 
using class protocol for constants, file names, and general inquiries. The environment 
variables protocol supplies information about the environment at the time Smalltalk 
was invoked. 

Instance Protocol 



Note: The only instance messages the typical user would 
send to an instantiated UTekSysytemCall are value 
or Invoke (inherited from AlmSystemCall). 
Remember that invoke does not perform error handling. 

Initialize-release methods set up the instance variables and operation type of a 
system call, and set up arguments, if any, to be passed to the call. 

The accessing method at:put: places an argument to the call in the position 
specified. 

Constants methods return symbols or corresponding values, as specified, from the 
SystemCallKeywords dictionary. Superclass constants methods return information 
from the OSConstants and ErrorConstants pools. 

Errors methods provide several formats of error messages. 

Execution methods set instance variable D10ut to true, provide methods to execute 
a system call with error handling, and invoke the Smalltalk primitives for signal and 
system operations. 
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The operation type methods set instance variable operationType to #signal Invoke in 
order to invoke a signal/semaphore primitive or to #waitlnvoke to make a wait or 
wait3 system call. 7 ho superclass implements the methods displayOperation and 
systemOperatlon. 

Portable subtask operations is also found under class protocol. Class protocol named 
"portable" causes creation of an instance of UTekSysytemCall; then the system call 
is made and the return value causes an error notifier if the call failed. You will see 
that InsXance portable subtask operations do not make a system call — they supply 
information available after awa/7 system call has executed. 

The printing method prIntOn: prints the system call and its arguments using a 
format similar to the C specification for the system call. 

Examples 

The following example illustrates accessing the shell environment. 
OS originalEnvironment at: #HOME. 

If you execute the preceding code in a workspace with "printit", the string 
representing your home directory will be printed. The following code will change 
your current directory to the directory above your current one. 

OS changeDirectory: '..'. 
OS currenlDirectoryName. 

If you execute the preceding code in a workspace with "printit", the string 
representing the directory will be printed. The string will have the trailing T 
separator. 

You can return to your home directory this way: 

OS changeDirectory: (OS originalEnvironment at: #HOME). 

The following code can be executed in a workspace. It illustrates various system 
calls for file operations found in the class message category portable file operations. 
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fd «- OS open: Too'. 

OS write: fd from: 'Hi, folks!' size: 10. 

OS seek: fd to: 0. 

answer <r- String new: 10. 

OS read: fd into: answer. 

OS closeFile: fd. 

Transcript cr; show: answer. 

This is what occurs in the example above. A file named 'foo' is created on the disk 
and its file descriptor is assigned \ofd. The string 'Hi, folks!', which contains 10 
bytes, is written to Too'. The file pointer is positioned at the beginning of file 'foo' by 
the seek: method with ':s the file position argument. Note that 'foo' is always 
referred to by its file descriptor, not its name, when making system calls. Next, an 
instance of String is created and assigned to answer. The method readrinto: fills 
the string with data from 'foo'. Try changing the size of answer to 8 and to 12 to see 
the different results in your System Transcript. The file is closed using the 
closeFlIe: method inherited from AimSystemCall. Closing frees the file descriptor, 
but 'foo' will still exist on the disk. To remove the file from the disk, you have to 
make another system call, like this: 

OS remove: 'foo'. 



Related Classes 

AbstractSystemCail 

AimSystemCall 

Subtask 
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ExternalBinaryData variableByteSubclass: #Utsname 


instance VariableNames: 


" 


classVariableNames: 


'MachineDatalndex NameLength 




NodenameDatalndex ReleaseDatalndex 




SysnameDatalndex VersionDatalndex ' 


poolDictionaries: 


" 


category: 


'OS-Parameters' 



Summary 

utsname provides accessing protocol for the following C structure. 

struct utsname { 

char sysname[9]; 

char nodename[9]; 

char release[9]; 

char version[9]; 

char machine[9]; 
} 

The structure is documented under uname(2) in the manual UTek Command Reference, 
Volume!. 

Class Variables 

MachineDatalndex 

NodenameDatalndex 

ReleaseDatalndex 

SysnameDatalndex 

VersionDatalndex 

Each C structure class variable holds the offset of a single field in the 
structure. The name of a class variable is constructed from a field name 
with the string 'Datalndex' appended. For example, the class variable 
MachineDatalndex holds the offset of the "machine" field. 



Tektronix Smalltalk Reference Manual 265 



Utsname OS-Parameters 



NameLength <lnteger> 

Holds the constant. 9, of the char fields of the utsname structure. 



Instance Methods 

accessing 



machine 

Return the value of the structure field named machine. 

nodename 

Return the value of the structure field named nodename. 

reieasa 

Return the value of the structure field named releare. 

sysname 

Return the value of the structure field named sysname. 

version 

Return the value of the structure field named version. 



printing 



printOn: aStream 

Print the receiver on aStream. 



Class Methods 



class initialization 

initialize 

Assign offset values to the class variables and define the size of the 
structure. 

instance creation 

unamo 

Return an initialized instance. 

Rationale 

The structure is used in support of the following UTek system call: 
uname(2) 

Related Classes 

UTel(SystemCall implements the system call listed above. 
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VirtualStrikeFont Graphics-Support 



Object subclass: #VirtualStrikeFont 

instanceVariableNames: 
class VariableNames: 
poolDictionaries: 
category: 


'name ascent descent ' 
'Graphics-Support' 



Summary 

A VirtualStrikeFont represents a StrlkeFont that has not been constructed in the 
image. A VirtualStrikeFont contains the name of the font that either StrlkeFont 
knows how to read or can be synthesized. VIrtualStrlkeFonts are converted to 
their corresponding StrlkeFont whenever they are referenced in a TextStyle, via 
the accessing method fontAt:. 

Instance Variables 

ascent <lnteger> 

The largest distance from the baseline to the top of any character in this 
font. 

descent <lnteger> 

The largest distance from the baseline to the bottom of any character in 
this font. 

name <String> 

The font name. 

Instance Methods 

accessing 

ascent 

Return the instance variable ascent. 

ascent: aninteger 

Set the ascent to aninteger. 
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descent 

Return the instance variable descent. 

descent: aninteger 

Set the descent to aninteger. 

name 

Answer the VirtualStrikeFont's name. 

name: aVirtualStrikeFontName 

Set the VirtualStrikeFont's name to aVirtualStrikeFontName, a String. 



testing 



isVlrtual 

Since the receiver is a VirtualStrikeFont, return true. 



Class Methods 



instance creation 

name: aString 

Return an instance with the name, aString. 

Rationale 

An instance of VirtualStrikeFont has been registered with the FontManager, but 
has not been loaded in the Image. This class enables you to create a TextStyle 
with an array of fonts, but save Smalltalk memory by not actually having the fonts in 
your image until they are accessed for use. When a "virtual" font is converted to a 
"real" StrlkeFont your image uses more memory. 

Discussion 

When an instance of this class is created, its name is assigned. Instances are 
created by the TextStyleManager text style instance creation methods, and that is the 
recommended way to create VIrtualStrlkeFonts. The instance creation method, 
name:, is called by a method in StrikeFontManager. 

Accessing methods return or set the values of instance variables. 

The testing method isVIrtual returns true. 
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Related Classes 

StrikaFont 
StrikeFontManager 
TextStyle 
TextStyleManager 
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Wait 



OS-Parameters 



ExternalBinaryData variableByteSubclass: UVJah 


instance VariableNames: 


" 


classVariabieNames: 


'CoredumpBltPosltion CoredumpDatalndex 




RetcodeDataindex StatusDatalndex 




StopsigDatalndex StopvalDatalndex 




TermsigDatalndex TermsigMask ' 


poolDlctionaries: 


" 


category: 


'OS-Parameters' 



Summary 



Wait provides accessing protocol for the following C union. 



/* used in syscall */ 



union wait { 
int w_status; 
/* 

* Terminated process status 
♦/ 

struct { 

unsigned short 
unsigned short 
unsigned short 
unsigned short 
}w_T; 
/♦ 

* Stopped process status. Returned 

* only for traced children unless requested 

* with the WUNTRACED option bit. 
♦/ 



:16: 

w_Retcode:8; 
w_Coredump:1; 
w_Termsig:7; 



/♦ pad to make full 32 bits */ 
/♦ exit code if w_termsig==0 ♦/ 
/♦ core dump indicator ♦/ 
/♦ termination signal */ 



} 



struct { 

unsigned short 
unsigned short 
unsigned short 
}w_S; 



:16; /♦ pad to make full 32 bits */ 

w_Stopsig:8; /♦ signal that stopped us */ 
w_Stopval:8; /* « W_STOPPED if stopped ♦/ 



The wait system call is documented under wait(2) in the manual UTek Command 
Reference, Volume 2. 
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Wait- — OS-.Earajneters 



Class Variables 

CoredumpDatalndex 

RetcodeDatalndex 

StatusDatalndex 

StopsigDatalndex 

StopvalDatalndex 

TermsigDatalndex 

Each external data binary subclass class variable holds the offset of a 
single field in the structure or union. The name of a class variable is 
constructed from a field name, stripped of its prefix, with the string 
'Datalndex' appended. For example, the class variable 
CoredumpDatalndex holds the offset of the "w_Coredump" field. 

CoredumpBitPosition <lnteger> 

Holds the constant, 8, for the bit position of the core dump indicator bit in 
the w_Coredump field. 

TermsigMask <lnteger> 

Holds the constant, 127, used to mask the termination signal bits in the 
w_Coredump field. 



Instance Methods 

accessing 



coredump 

Return the value of the union field named coredump. 

retcoda 

Return the value of the union field named retcode. 

status 

Return the value of the union field named status. 

stopslg 

Return the value of the union field named stopsig. 



Bi 



Wait OS-ParamQters. 



stopval 

Return the value of the union field named stopval. 

termsig 

Return the value of the union field named termsig. 



printing 



printOn: aStream 

Print the receiver on aStream. 



Class Methods 



class initialization 

Initialize 

Assign offset values to the class variables and define the size of the union. 

Rationale 

The wait union is used in support of the following UTek system calls: 

wait(2) 
waU3(2) 

Related Classes 

UTel<SystemCali implements the system calls listed above. 
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WorkspaceController Interface-Text 



StringHolderController subclass: #WorkspaceController 

instanceVariableNames: 

classVariableNames: 'Workspace YeliowButtonMenu 

Workspace YellowButtonMessages ' 
poolDictionaries: 
category: 'Interface-Text' 



Summary 

WorkspaceController provides additional control for workspaces. Results of 
expressions in workspaces can be inspected. 

Class Variables 

Workspace YeliowButtonMenu <PopUpMenu> 
Yellow button menu in workspaces. 

Workspace YellowButtonMessages <Array> 

An array of symbols, each one being a selector that implements the 
corresponding Item in Workspace YeliowButtonMenu. 

Instance Methods 

menu messages 

accept 

Accept the workspace contents. 

inspectit 

Treat the current text selection as an expression; evaluate it. Open an 
Inspector on the result. 



Class Methods 



class initializaiion 

initialize 

initialize the yellow button pop-up menu and corresponding messages. 



Tektronix Smalltalk Reference Manual 275 



WorkspacqContrqller interface-Text 



Flatipnale 

This class allows the addition of middle-button menu items for workspaces. 

Discussion 

Using WorkspacaControllar, it is possible for you to add middle-button menu 
choices for workspaces. This implementation adds the "inspect it" menu choice. 
Expressioris in ordinary workspaces and in the System Workspace can be selected 
and an Inspector will be opened on their results. Another menu choice you might 
add to >A/orkspaces;is "file out" t- it is available as a fileln. Read about filelns in the 
TetronixSpiqlltalk Users manuzl 

Menu messages protocol includes the methods for middle-button menu choices. 
Accept has been reirrtplemented to save the contents of a workspace as text — this 
allows font^used in the workspace to be saved with the text. 

Class initializatiQn protocol initializes the two class variables — the pop-up menu and 
corresponding messages. 

Belate^l Classes 

Workspaco 
Workspace View 
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